Instance endpoints

The instance endpoints let you work with the Clym account behind one of your customers — their company, their property and the users who can access them — with your Partner API key. They live under https://partners.clym.io/api/portal/instance.

Area	Path	Use it to
Company	/portal/instance/company and its sub-paths	Read and update the company, manage its representatives, list consent records, and look up countries, sectors, industries and criteria groups.
Property	/portal/instance/property and its sub-paths	Read the property, manage its subdomains and widget assets, and send implementation instructions.
Access	/portal/instance/access/users and its sub-paths	List, grant, update and remove user access to the company, or provision a user and get a sign-in link.

Enabling instance endpoints

Instance 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 to enable them.

Identifying the merchant

Every call must say which customer it acts on, using one of these parameters:

Name	Type	Description
merchant_id	string	One of your merchants: either the merchant's Clym id or the merchant_id you assigned to it. 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.

If you send more than one, merchant_id takes priority over domain_id, and domain_id over property_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. For example, GET /portal/instance/company/records returns only that property's consent records with merchant_id or property_id, and all of the company's consent records with domain_id.

Pass the identifier in the query string. For POST and PUT requests you can also include it in the JSON body. Values longer than 36 characters are ignored, so if the merchant_id you assigned is longer, use the merchant's Clym id instead.

Sending parameters

• GET and DELETE: send parameters in the query string.
• POST and PUT: send parameters as a JSON body with the Content-Type: application/json header.
• Array query parameters: repeat the key (?ids=a&ids=b) or separate the values with commas (?ids=a,b). Bracket syntax such as ids[]=a is not supported and 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" }'

Responses use the same { result } and { meta, result } envelope as the rest of the API, and errors use the standard error envelope (see Errors).

Errors

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.