Integrations

In Cerby, integrations are the connections between seat-based and paid social apps with a Cerby workspace. The goal is to enable companies to centralize in Cerby the lifecycle management of user accounts within these apps, characterized by having collaboration spaces (workspaces, teams, or dashboards) and individual seats or licenses for user access. The connection is based on API requests or automated jobs.

Depending on the API endpoint, you can retrieve any of the following two objects from an integration:

  • integration object: Contains information about the app connected to Cerby, the date when the integration was created, the user who created and last updated the account, and other relevant attributes.

  • entitlement object: Contains information about the available user roles in the app or the roles assigned to a user. In the second case, the entitlement object is an attribute of a user object.

A business-hub object is created in Cerby when you connect an integration through the Cerby web app, whereas an entitlement object is created in response to a specific request you make to the Cerby API.

With the Cerby API, you can retrieve specific integrations by providing their ID, the available entitlements, all the users in an integrations, and specific users in an integration by providing their ID. Also, you can update the entitlements of a user in an integration.

To learn more about integrations, refer to the Business Hubsarrow-up-right article collection on the Cerby Help Center.

List integrations

get

With a GET request to the /integrations endpoint, you can retrieve the list of all your integrations in Cerby.

Important: The API scope required to use this endpoint is: Read integrations.

Query parameters
page[number]integer · min: 1Optional

The page number to retrieve in the paginated list.

Default: 1
page[size]integer · min: 1 · max: 100Optional

The number of items to return per page.

Default: 25
Responses
chevron-right
200

OK

application/json
get
/integrations

Retrieve integration by ID

get

With a GET request to the /integrations/{id} endpoint, you can retrieve the information of an integration by providing its ID.

Important: The API scope required to use this endpoint is: Read integrations.

Path parameters
idstring · uuidRequired

The unique identifier of the integration.

Responses
chevron-right
200

OK

application/json
get
/integrations/{id}

List users of an integration

get

With a GET request to the /integrations/{id}/users endpoint, you can retrieve the list of users of an integration by providing the integration ID.

Important: The API scopes required to use this endpoint are: Read users and Read integrations.

Path parameters
idstring · uuidRequired

The unique identifier of the integration.

Query parameters
page[number]integer · min: 1Optional

The page number to retrieve in the paginated list.

Default: 1
page[size]integer · min: 1 · max: 100Optional

The number of items to return per page.

Default: 25
Responses
chevron-right
200

OK

application/json
get
/integrations/{id}/user

Invite user to an integration

post

With a POST request to the /integrations/{id}/users endpoint, you can invite a user to an integration by providing the integration ID.

Important:

  • The required API key scopes to access this resource are: Write integrations and Read automated jobs.

  • This endpoint initiates an automated job. Note that the automation process is asynchronous, which means it may take some time to complete. We recommend making monitoring calls to the Retrieve job by ID endpoint to check the status of the automation and ensure it has been completed successfully.

Path parameters
idstring · uuidRequired

The unique identifier of the integration.

Body
Responses
chevron-right
200

OK

application/json
post
/integrations/{id}/user

List integration entitlements

get

With a GET request to the /integrations/{id}/entitlements endpoint, you can retrieve a list of the entitlements (roles) available for assignment in an integration by providing the integration ID.

Important: The API scope required to use this endpoint is: Write integrations.

Path parameters
idstring · uuidRequired

The unique identifier of the integration.

Responses
chevron-right
200

OK

application/json
get
/integrations/{id}/entitlements

Retrieve user of an integration

get

With a GET request to the /integrations/{id}/users/{userId} endpoint, you can retrieve a user of an integration by providing the user and integration IDs.

Important: The API scopes required to use this endpoint are: Read users and Read integrations.

Path parameters
idstring · uuidRequired

The unique identifier of the integration.

userIdstring · uuidRequired

The unique identifier of the user to retrieve.

Responses
chevron-right
200

OK

application/json
get
/integrations/{id}/users/{userId}

Remove user from an integration

delete

With a DELETE request to the /integrations/{id}/users/{userId} endpoint, you can remove a user from an integration by providing the integration and the user IDs.

Important:

  • The required API key scopes to access this resource are: Write integrations and Write automated jobs.

  • This endpoint initiates an automated job. Note that the automation process is asynchronous, which means it may take some time to complete. We recommend making monitoring calls to the Retrieve job by ID endpoint to check the status of the automation and ensure it has been completed successfully.

Path parameters
idstring · uuidRequired

The unique identifier of the integration.

userIdstring · uuidRequired

The unique identifier of the user to be removed.

Responses
chevron-right
200

OK

application/json
delete
/integrations/{id}/users/{userId}

Update a user’s entitlements in an integration

patch

With a PATCH request to the /integrations/{id}/users/{userId} endpoint, you can update a user’s entitlements in an integration by providing the user and integration IDs.

Important:

  • The required API key scopes to access this resource are: Write integrations and Write automated jobs.

  • This endpoint initiates an automated job. Note that the automation process is asynchronous, which means it may take some time to complete. We recommend making monitoring calls to the Retrieve job by ID endpoint to check the status of the automation and ensure it has been completed successfully.

Path parameters
idstring · uuidRequired

The unique identifier of the integration.

userIdstring · uuidRequired

The unique identifier of the user to update.

Body
Responses
chevron-right
200

OK

application/json
patch
/integrations/{id}/users/{userId}

Add or remove a user's entitlements in an integration

patch

With a PATCH request to the /integrations/{id}/users/{userId}/entitlements endpoint, you can add or remove a user’s individual entitlements in an integration, without replacing all existing entitlements, by providing the user and integration IDs.

Important:

  • The required API key scopes to access this resource are: Write integrations and Write automated jobs.

  • This endpoint initiates an automated job. Note that the automation process is asynchronous, which means it may take some time to complete. We recommend making monitoring calls to the Retrieve job by ID endpoint to check the status of the automation and ensure it has been completed successfully.

Path parameters
idstring · uuidRequired

The unique identifier of the integration.

userIdstring · uuidRequired

The unique identifier of the user to update.

Body
Responses
chevron-right
200

OK

application/json
patch
/integrations/{id}/users/{userId}/entitlements

Last updated