Create Profile API
The Create Profile API creates a labeled profile that groups integrations under a single name. Send a POST request to {{API_BASE_URL}}/v1/profiles/ with an x-access-key header and a JSON body, then supply the returned profile id under the name profileId in the connect call for a platform.
Create Profile API — operation summary
Profiles group integrations under a label. Creating a profile first gives you a stable container, and the returned id is supplied under the name profileId in the connect call for a platform, so the new integration is associated with that profile. This separation keeps the profile label independent from any single platform connection.
Authorization
Authenticate the request with the x-access-key header. The header value is shown as <token> in the contract, and the header is sent in the request header rather than in the JSON body. Send Content-Type: application/json alongside it so the request body is parsed as JSON.
Request body and input contract
The request body is application/json. The name field is required and must be a string between 1 and 200 characters long, for example a company name or a personal brand label. The description field is optional and, when supplied, must be a string of up to 1000 characters describing what the profile is for. Check both length limits before sending, because the contract defines them as validation constraints on the fields themselves.
Response body and field map
A successful creation returns status 201 with an application/json body. The top-level success field is a boolean, and the profile object contains the created profile. Its id is the identifier to reuse as profileId for integration association, name echoes the profile name, and description is a string or null. The integrationCount field is an integer greater than or equal to 0 indicating how many integrations are associated with the profile, and createdAt and updatedAt are date-time strings recording when the profile was created and last updated. See the request and response tables and the worked examples for the complete field maps.
Worked example
The worked examples show the origin-modularized POST sample and the 201 response sample exactly as defined by the contract, with only the origin replaced by {{API_BASE_URL}}. Replace the <token> placeholder with your access key value and the name placeholder with the profile name you want to create. After a 201 response, read profile.id from the response body and store it for the next step.
Using the returned profileId
Once you have the returned profile id, supply it under the name profileId in the connect call for a platform so the resulting integration is associated with the profile you just created. If the response does not contain a profile id, do not proceed to association, because there is no profileId value to supply. Verify integrationCount in later profile responses to confirm how many integrations are associated with the profile.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
| name | string | Required | 1 <= length <= 200 | Profile name (e.g. "Acme Co", "Personal Brand") |
| description | string | Optional | length <= 1000 | Optional description of what this profile is for |
Request body: application/json
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
| success | boolean | Required | Top-level success flag | |
| profile | object | Required | Created profile object | |
| profile.id | string | Required | Profile id; supply as profileId when associating an integration | |
| profile.name | string | Required | Profile name | |
| profile.description | string | null | Required | Profile description, or null | |
| profile.integrationCount | integer | Required | 0 <= value | Number of active integrations associated with this profile |
| profile.createdAt | string | Required | date-time | Creation timestamp |
| profile.updatedAt | string | Required | date-time | Last update timestamp |
Response body: 201 application/json
| Check | Expected result | Action if it fails |
|---|---|---|
| Authorization header present | x-access-key header sent with <token> value | Add the x-access-key header and retry |
| name length | 1 <= length <= 200 | Shorten or lengthen name to fit the limit |
| description length | length <= 1000 when supplied | Shorten description or omit it |
| Response status | 201 application/json | Do not use a profile id unless the response contains profile.id |
| Association step | profileId supplied in the connect call for a platform | Use the returned profile.id value exactly |
Limited to source-supported constraints; no additional error codes are defined in the supplied source
Frequently asked questions
What is required to create a profile?
Send POST to {{API_BASE_URL}}/v1/profiles/ with an x-access-key header and a JSON body containing the required name field. The description field is optional.
How do I associate an integration with a newly created profile?
Supply the returned profile.id under the name profileId in the connect call for a platform, so the new integration is associated with that profile.
What length limits apply to the request fields?
The name must be a string with length from 1 to 200 characters. The optional description must be a string with length up to 1000 characters when supplied.
curl -X POST "{{API_BASE_URL}}/v1/profiles/" \
-H "Content-Type: application/json" \
-H "x-access-key: <token>" \
-d '{
"name": "string"
}'{
"success": true,
"profile": {
"id": "string",
"name": "string",
"description": "string",
"integrationCount": 0,
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| body#1 | body | object | __0 | Yes | ||
| body#1 | body.name | string | __1 | Yes | Profile name (e.g. "Acme Co", "Personal Brand") | kind: schemaLength; value: 1 <= length <= 200 |
| body#1 | body.description | string | __2 | No | Optional description of what this profile is for | kind: schemaLength; value: length <= 1000 |
| response#2 | response | object | __0 | |||
| response#2 | response.success | boolean | __1 | Yes | ||
| response#2 | response.profile | object | __2 | Yes | ||
| response#2 | response.profile.id | string | __3 | Yes | ||
| response#2 | response.profile.name | string | __4 | Yes | ||
| response#2 | response.profile.description | string | null | __5 | Yes | ||
| response#2 | response.profile.description[variant1] | string | __5_type:string | |||
| response#2 | response.profile.description[variant2] | null | __5_type:null | |||
| response#2 | response.profile.integrationCount | integer | __6 | Yes | Number of active integrations bound to this profile | kind: schemaRange; value: 0 <= value |
| response#2 | response.profile.createdAt | string | __7 | Yes | kind: schemaFormat; value: date-time | |
| response#2 | response.profile.updatedAt | string | __8 | Yes | kind: schemaFormat; value: date-time |