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 Hubs 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

200

OK

application/json

401

Unauthorized - User is not authorized to perform the request.

application/json

get

/integrations

HTTPcURLJavaScriptPython

GET /api/v1/integrations HTTP/1.1
Host: my-workspace.cerby.com
Accept: */*

{
  "data": [
    {
      "attributes": {
        "application": "youtube_tenant",
        "createdAt": "2024-03-20T20:11:13+00:00",
        "createdBy": "1ab381d7-abcd-dcab-ac7b-343cd6d12345",
        "label": "Youtube acme",
        "updatedAt": "2024-03-25T15:20:09+00:00",
        "workspace": "acme"
      },
      "id": "1234422e-abcd-4ee0-3322-54eecbcbab00",
      "type": "account"
    }
  ],
  "links": {
    "next": "/api/v1/integrations?page%5Bnumber%5D=2&page%5Bsize%5D=20",
    "previous": null,
    "self": "/api/v1/integrations?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "page": {
      "maxSize": 100,
      "total": 1
    }
  }
}

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

200

OK

application/json

401

Unauthorized - User is not authorized to perform the request.

application/json

404

Not found - Resource not found.

application/json

get

/integrations/{id}

HTTPcURLJavaScriptPython

GET /api/v1/integrations/{id} HTTP/1.1
Host: my-workspace.cerby.com
Accept: */*

{
  "data": {
    "attributes": {
      "application": "youtube_tenant",
      "createdAt": "2024-03-20T20:11:13+00:00",
      "createdBy": "1ab381d7-abcd-dcab-ac7b-343cd6d12345",
      "label": "Youtube acme",
      "updatedAt": "2024-03-25T15:20:09+00:00",
      "workspace": "acme"
    },
    "id": "a427011c-abcd-1234-8393-43abcbcb1234",
    "type": "account"
  }
}

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

200

OK

application/json

401

Unauthorized - User is not authorized to perform the request.

application/json

404

Not found - Resource not found.

application/json

get

/integrations/{id}/user

HTTPcURLJavaScriptPython

GET /api/v1/integrations/{id}/user HTTP/1.1
Host: my-workspace.cerby.com
Accept: */*

{
  "data": [
    {
      "attributes": {
        "email": "[e-mail]",
        "entitlements": [
          {
            "attributes": {
              "group": "primary",
              "key": "VIEWER_LIMITED",
              "label": "TENANT_VIEWER_LIMITED_DESC",
              "value": "VIEWER_LIMITED"
            },
            "id": "VIEWER_LIMITED",
            "type": "entitlement"
          }
        ],
        "firstName": "Jane",
        "isGuest": false,
        "lastName": "User",
        "role": "collaborator",
        "status": "live"
      },
      "id": "04393f7e-2244-1234-abcd-fca770123456",
      "type": "user",
      "meta": {
        "dynamicFields": {
          "customAttribute1": "value1",
          "customAttribute2": 123,
          "customAttribute3": true
        }
      }
    },
    {
      "attributes": {
        "email": "[e-mail]",
        "entitlements": [
          {
            "attributes": {
              "group": "primary",
              "key": "EDITOR_LIMITED",
              "label": "YOUTUBE_TENANT_EDITOR_LIMITED_DESC",
              "value": "EDITOR_LIMITED"
            },
            "id": "EDITOR_LIMITED",
            "type": "entitlement"
          }
        ],
        "firstName": "Joe",
        "isGuest": false,
        "lastName": "Doe",
        "role": "owner",
        "status": "live"
      },
      "id": "0c9dabcb-1234-abcd-1234-1234c8003555",
      "type": "user",
      "meta": {
        "dynamicFields": {
          "customAttribute1": "value2",
          "customAttribute2": 456,
          "customAttribute3": false
        }
      }
    }
  ],
  "links": {
    "next": null,
    "previous": null,
    "self": "/api/v1/integrations/d538422e-b135-4ee0-8393-54eecbcb4a07/users?page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "page": {
      "maxSize": 100,
      "total": 4
    }
  }
}

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

application/json

Responses

200

OK

application/json

401

Unauthorized - User is not authorized to perform the request.

application/json

404

Not found - Resource not found.

application/json

post

/integrations/{id}/user

HTTPcURLJavaScriptPython

POST /api/v1/integrations/{id}/user HTTP/1.1
Host: my-workspace.cerby.com
Content-Type: application/json
Accept: */*
Content-Length: 169

{
  "data": {
    "attributes": {
      "role": "account_owner",
      "entitlements": [
        {
          "id": "VIEWER_LIMITED"
        }
      ],
      "userIds": [
        "1cc381f7-9c52-419f-ac7b-ae3cd6d148d4"
      ]
    },
    "type": "invite_tenant_users"
  }
}

{
  "data": {
    "attributes": {
      "status": "created"
    },
    "id": "43c65e54-07fb-48c1-90e4-498d91b0f8b9",
    "type": "job"
  }
}

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

200

OK

application/json

401

Unauthorized - User is not authorized to perform the request.

application/json

404

Not found - Resource not found.

application/json

get

/integrations/{id}/entitlements

HTTPcURLJavaScriptPython

GET /api/v1/integrations/{id}/entitlements HTTP/1.1
Host: my-workspace.cerby.com
Accept: */*

{
  "data": [
    {
      "attributes": {
        "group": "primary",
        "key": "MANAGER",
        "label": "YOUTUBE_TENANT_MANAGER_DESC",
        "value": "MANAGER"
      },
      "id": "MANAGER",
      "type": "entitlement"
    },
    {
      "attributes": {
        "group": "primary",
        "key": "EDITOR",
        "label": "YOUTUBE_TENANT_EDITOR_DESC",
        "value": "EDITOR"
      },
      "id": "EDITOR",
      "type": "entitlement"
    },
    {
      "attributes": {
        "group": "primary",
        "key": "VIEWER_LIMITED",
        "label": "YOUTUBE1-Q_TENANT_VIEWER_LIMITED_DESC",
        "value": "VIEWER_LIMITED"
      },
      "id": "VIEWER_LIMITED",
      "type": "entitlement"
    }
  ]
}

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

200

OK

application/json

401

Unauthorized - User is not authorized to perform the request.

application/json

404

Not found - Resource not found.

application/json

get

/integrations/{id}/users/{userId}

HTTPcURLJavaScriptPython

GET /api/v1/integrations/{id}/users/{userId} HTTP/1.1
Host: my-workspace.cerby.com
Accept: */*

{
  "data": {
    "attributes": {
      "email": "[e-mail]",
      "entitlements": [
        {
          "attributes": {
            "group": "primary",
            "key": "EMPLOYEE",
            "label": "PINTEREST_BUSINESS_EMPLOYEE_DESC",
            "value": "EMPLOYEE"
          },
          "id": "EMPLOYEE",
          "type": "entitlement"
        }
      ],
      "firstName": "Joe",
      "isGuest": false,
      "lastName": "Doe",
      "role": "owner",
      "status": "live"
    },
    "id": "a4393f7e-1234-abcd-b23b-fca770912345",
    "type": "user",
    "meta": {
      "dynamicFields": {
        "customAttribute1": "value1",
        "customAttribute2": 123,
        "customAttribute3": true
      }
    }
  }
}

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

200

OK

application/json

401

Unauthorized - User is not authorized to perform the request.

application/json

404

Not found - Resource not found.

application/json

delete

/integrations/{id}/users/{userId}

HTTPcURLJavaScriptPython

DELETE /api/v1/integrations/{id}/users/{userId} HTTP/1.1
Host: my-workspace.cerby.com
Accept: */*

{
  "data": {
    "attributes": {
      "status": "created"
    },
    "id": "722fbd00-421f-4f7a-babc-b12348e2bb12",
    "type": "job"
  }
}

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

application/json

Responses

200

OK

application/json

401

Unauthorized - User is not authorized to perform the request.

application/json

404

Not found - Resource not found.

application/json

patch

/integrations/{id}/users/{userId}

HTTPcURLJavaScriptPython

PATCH /api/v1/integrations/{id}/users/{userId} HTTP/1.1
Host: my-workspace.cerby.com
Content-Type: application/json
Accept: */*
Content-Length: 91

{
  "data": {
    "type": "update_user_entitlement",
    "attributes": {
      "entitlements": [
        {
          "id": "VIEWER"
        }
      ]
    }
  }
}

{
  "data": {
    "attributes": {
      "status": "created"
    },
    "id": "add12344-6550-abad-67c9-315e734923a5",
    "type": "job"
  }
}

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

application/json

Responses

200

OK

application/json

401

Unauthorized - User is not authorized to perform the request.

application/json

404

Not found - Resource not found.

application/json

patch

/integrations/{id}/users/{userId}/entitlements

HTTPcURLJavaScriptPython

PATCH /api/v1/integrations/{id}/users/{userId}/entitlements HTTP/1.1
Host: my-workspace.cerby.com
Content-Type: application/json
Accept: */*
Content-Length: 95

{
  "data": {
    "add": {
      "entitlements": [
        {
          "id": "VIEWER"
        }
      ]
    },
    "remove": {
      "entitlements": [
        {
          "id": "EDITOR"
        }
      ]
    }
  }
}

{
  "data": {
    "attributes": {
      "status": "created"
    },
    "id": "add12344-6550-abad-67c9-315e734923a5",
    "type": "job"
  }
}