Instance endpoints
The instance endpoints act on the Clym account behind one of your customers: their company, their property, and the users who can access them. They live under https://partners.clym.io/api/portal/instance and use the same Partner API key as the rest of the API.
| Area | Path | Use it to |
|---|---|---|
| Company | /portal/instance/company |
Read and update the company, manage its representatives, list consent records, and look up countries, sectors, industries and criteria groups. |
| Property | /portal/instance/property |
Read the property, manage its subdomains and widget assets, and send implementation instructions. |
| Access | /portal/instance/access/users |
List, grant, update and remove user access to the company, or provision a user and get a sign-in link. |
These endpoints must be enabled for your partner account. Until they are, every call returns 403 with the code AUTH.ACCESS — ask your Clym account manager.
Identifying the merchant
Every call must say which customer it acts on:
| Name | Type | Description |
|---|---|---|
merchant_id |
string | One of your merchants, either its Clym id or the merchant_id you assigned. The merchant must be linked to an active domain. |
domain_id |
string | The id of one of your active domains, as returned by GET /portal/domains. |
property_id |
string | The instance_property_id of one of your active domains. |
Send it in the query string, or in the JSON body for POST and PUT. If you send more than one, merchant_id wins over domain_id, and domain_id over property_id. Values longer than 36 characters are ignored, so if the merchant_id you assigned is longer, use the merchant's Clym id.
On company endpoints the identifier also sets the scope: merchant_id and property_id limit property-specific results to that customer's property, while domain_id covers the whole company. GET /portal/instance/company/records, for example, returns one property's consent records with merchant_id or property_id, and all of the company's with domain_id.
Array parameters in the query string repeat the key (?ids=a&ids=b) or separate values with commas (?ids=a,b). Bracket syntax such as ids[]=a is silently ignored.
Example
curl --request GET \ --url 'https://partners.clym.io/api/portal/instance/company?merchant_id={MERCHANT_ID}' \ --header 'Authorization: Bearer {YOUR_API_KEY}'
curl --request PUT \ --url 'https://partners.clym.io/api/portal/instance/company?domain_id={DOMAIN_ID}' \ --header 'Authorization: Bearer {YOUR_API_KEY}' \ --header 'Content-Type: application/json' \ --data '{ "name": "My Company Inc" }'
Errors
Same envelopes as the rest of the API (see Errors), plus:
| Status | Code | Meaning |
|---|---|---|
400 |
DATA.API_REQUEST |
The request has no valid merchant_id, domain_id or property_id. |
400 |
DATA.MERCHANT_NOT_SETUP |
The merchant_id does not match one of your merchants, or the merchant is not linked to an active domain. |
403 |
AUTH.ACCESS |
Instance endpoints are not enabled for your partner account. |
403 |
DATA.API_ACCESS |
The domain or property is not one of your active domains. |
403 |
INSTANCE.ACCESS |
Provisioning access (POST /portal/instance/access/users/provision) is not available for your account. |
404 |
DATA.NOT_FOUND |
The first path segment after /portal/instance/ is not a supported resource. |
