Skip to content

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.

Create Profile API request fields
FieldTypeRequiredConstraintsDescription
namestringRequired1 <= length <= 200Profile name (e.g. "Acme Co", "Personal Brand")
descriptionstringOptionallength <= 1000Optional description of what this profile is for

Request body: application/json

Create Profile API response fields
FieldTypeRequiredConstraintsDescription
successbooleanRequiredTop-level success flag
profileobjectRequiredCreated profile object
profile.idstringRequiredProfile id; supply as profileId when associating an integration
profile.namestringRequiredProfile name
profile.descriptionstring | nullRequiredProfile description, or null
profile.integrationCountintegerRequired0 <= valueNumber of active integrations associated with this profile
profile.createdAtstringRequireddate-timeCreation timestamp
profile.updatedAtstringRequireddate-timeLast update timestamp

Response body: 201 application/json

Create Profile API validation and failure checks
CheckExpected resultAction if it fails
Authorization header presentx-access-key header sent with <token> valueAdd the x-access-key header and retry
name length1 <= length <= 200Shorten or lengthen name to fit the limit
description lengthlength <= 1000 when suppliedShorten description or omit it
Response status201 application/jsonDo not use a profile id unless the response contains profile.id
Association stepprofileId supplied in the connect call for a platformUse 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.

Create Profile API request example
curl -X POST "{{API_BASE_URL}}/v1/profiles/" \
  -H "Content-Type: application/json" \
  -H "x-access-key: <token>" \
  -d '{
    "name": "string"
  }'
Create Profile API 201 response example
{
  "success": true,
  "profile": {
    "id": "string",
    "name": "string",
    "description": "string",
    "integrationCount": 0,
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
body#1bodyobject__0Yes
body#1body.namestring__1YesProfile name (e.g. "Acme Co", "Personal Brand")kind: schemaLength; value: 1 <= length <= 200
body#1body.descriptionstring__2NoOptional description of what this profile is forkind: schemaLength; value: length <= 1000
response#2responseobject__0
response#2response.successboolean__1Yes
response#2response.profileobject__2Yes
response#2response.profile.idstring__3Yes
response#2response.profile.namestring__4Yes
response#2response.profile.descriptionstring | null__5Yes
response#2response.profile.description[variant1]string__5_type:string
response#2response.profile.description[variant2]null__5_type:null
response#2response.profile.integrationCountinteger__6YesNumber of active integrations bound to this profilekind: schemaRange; value: 0 <= value
response#2response.profile.createdAtstring__7Yeskind: schemaFormat; value: date-time
response#2response.profile.updatedAtstring__8Yeskind: schemaFormat; value: date-time