Skip to main content

Collections

What a Collection Is​

A collection represents one outside system, for example PolicyHub KYC or a partner billing service. Everything set on the collection is shared by every API inside it: the base address, the headers, the parameters and the way to authenticate. Setting these once keeps each API short and means a change, such as a new token, is made in one place.

Creating a Collection​

  1. Open Configuration → Integrations → API Integrations.
  2. Click Create. A New Collection form opens beside the list.
  3. Enter the Collection Name and the Base URL. Both are required.
  4. Add default headers and parameters if every API needs them.
  5. Choose the Auth Type and enter its details. Add collection scripts if the outside system needs a login step. See Collection Scripts and Authentication.
  6. Click Save.

New Collection form with Collection Name, Base URL, Default Headers, Default Params and Auth Type set to No Auth, followed by collection scripts

Figure 1. The New Collection form before any values are entered. Collection Name and Base URL are required.

Field Reference​

FieldPurpose
Collection NameA label for the list, for example PolicyHub KYC.
Base URLThe root address of the outside API, for example https://api.policyhub.example.com. Each API adds its own path to it.
Default HeadersHeaders sent on every API in the collection, such as Content-Type: application/json. Each row has an On switch, a key and a value.
Default ParamsQuery parameters sent on every API in the collection.
Auth TypeHow every API authenticates by default.
Collection ScriptsA Pre Script and a Post Script that run around every API in the collection.
tip

When you type a path in an API, starting it with a slash inserts the base address for you. You only type the path, for example /v2/customers.

Authentication Types​

TypeFields
No AuthNothing is sent.
API KeyA key name, where to place it (header or query parameter) and the key value.
Bearer TokenA token, sent as Authorization: Bearer followed by the token. The Token field is required.
Basic AuthA user name and a password.
info

Most outside systems use a Bearer Token. If the token has to be fetched by a login call, leave the token empty here and let a collection script fetch and save it. See Collection Scripts and Authentication.

Managing Collections​

Each collection appears in the list with its base address and a badge that shows how many APIs it holds. The edit icon opens the collection for changes, and the delete icon removes it. Click the collection name to open its APIs.

Edit Collection form for PolicyHub KYC with a Content-Type header, a Bearer Token auth type and a masked token, with a Delete button and the collection in the list showing zero APIs

Figure 2. The PolicyHub KYC collection after it is saved. The Edit Collection form shows the saved headers and authentication.

warning

Deleting a collection removes the APIs inside it. Check that no CRM module or workflow uses them first.