Skip to content

Create Profile API

The Create Profile API creates a profile to group one or more social integrations. Use it when you need a named container before connecting accounts, so each resulting integration can be bound to the correct profile instead of being left ungrouped.

Create Profile API: purpose and endpoint

The Create Profile API creates a profile to group one or more social integrations. Send a POST request to the endpoint shown in the Endpoint table below, with the headers and JSON body shown in the Create a profile with cURL example. The profile name is the only required body field, and it does not need to be unique, so you can reuse a familiar label for separate profiles if that helps your own organization. The optional description is free-form text for distinguishing profiles internally, such as which team or brand the grouped social integrations belong to. Before sending, check that the profile name is between 1 and 200 characters and that any description is no more than 1000 characters, because exceeding those limits is a validation error rather than a successful creation.

Body Parameters and saving the returned ID

The Body Parameters table gives the exact input contract for this endpoint. Provide name as a required string and description only when you want to add context. If the request succeeds, the Successful profile creation response example shows the envelope to expect: a success flag set to true and a profile object containing the new profile. Save profile.id immediately after creation. That value is the identifier you will later pass as profileId when calling /v1/connect/:platform, which binds the resulting integration to this profile. If you lose the returned ID, you will need to find the profile again through the list operation rather than guessing it from the name, since names are not unique.

Response Fields

The Response Fields table maps every field in the profile object. The id field is the profile ID to use as profileId on connect URLs. The name and description echo the values you provided, with description returned as null when none was supplied. The integrationCount field reports the number of active integrations bound to this profile and is always 0 immediately after create, so a non-zero value right after creation would indicate you are reading a different profile or a later state. Both createdAt and updatedAt are ISO 8601 timestamps recording when the profile was created and last updated. Treat the timestamps as opaque strings for ordering and display unless your application explicitly parses them.

Status Codes and next step

The Status Codes table lists the outcomes documented for this endpoint. A 201 response means Profile created and returns the profile object described above. A 400 response means a validation error, such as a missing name or a value that exceeded its length limit. When you receive a 400, correct the request body against the Body Parameters table and retry with a valid profile name; do not reuse a partial or malformed payload. No other status codes are documented for this endpoint on this page, so do not build retry or error-handling logic around codes that are not listed here. After a successful creation, the next step is to connect a social integration and pass the saved profile ID as profileId on the connect URL so the integration is grouped under the new profile from the start.

Endpoint
ItemValue
MethodPOST
Path{{API_BASE_URL}}/v1/profiles

Origin is modularized as {{API_BASE_URL}}; method and path are preserved exactly.

Body Parameters
ParameterTypeRequiredDescription
namestringYesProfile name (1–200 chars). Doesn't need to be unique.
descriptionstringNoFree-form description (max 1000 chars).
Response Fields
FieldTypeDescription
idstringProfile ID — use as profileId on connect URLs
namestringThe name you provided
descriptionstring | nullThe description you provided
integrationCountintegerNumber of active integrations bound to this profile (always 0 immediately after create)
createdAtstringISO 8601 timestamp
updatedAtstringISO 8601 timestamp
Status Codes
CodeMeaning
201Profile created
400Validation error (missing name, exceeded length, etc.)
Create a profile with cURL
curl -X POST {{API_BASE_URL}}/v1/profiles \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Co",
    "description": "Example post details."
  }'
Successful profile creation response
{
	"success": true,
	"profile": {
		"id": "65ab...",
		"name": "Acme Co",
		"description": "Example post details.",
		"integrationCount": 0,
		"createdAt": "2026-05-03T08:33:36.445Z",
		"updatedAt": "2026-05-03T08:33:36.445Z"
	}
}
Contract example 1
POST {{API_BASE_URL}}/v1/profiles