POST/v1/profiles

Create a profile

Creates a new profile under your developer account. A profile represents a single end user in your application and acts as the container for every social account that user connects through Synposter, so you typically create one profile per user the first time they sign up.

curl -X POST https://api.synposter.com/v1/profiles \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice's Brand",
    "externalId": "user-42",
    "metadata": {
      "tier": "pro"
    }
  }'

Body

Field	Type	Required	Description
name	string	Yes	A human-readable label for the profile, between 1 and 100 characters. This is mostly for your own dashboards and logs and isn't shown to end users.
externalId	string	No	Your own identifier for this profile, typically the user's primary key in your own database. It must be unique within your developer account, and can be up to 200 characters long. Setting this lets you look the profile back up by your own ID instead of Synposter's UUID.
metadata	object	No	An arbitrary JSON object you can use to attach extra context to a profile. Synposter stores it as-is and returns it unchanged on read; we never inspect or interpret the contents.

Response (201)

json

{
  "id": "9b3a...",
  "name": "Alice's Brand",
  "externalId": "user-42",
  "metadata": { "tier": "pro"},
  "createdAt": "2026-04-28T12:00:00Z",
  "updatedAt": "2026-04-28T12:00:00Z"
}

Field	Type	Required	Description
id	string	Yes	Synposter's UUID for the new profile. Use this any time you need to reference the profile in another endpoint.
name	string	Yes	The human-readable label you supplied in the request, returned unchanged.
externalId	string \| null	Yes	Your own identifier for this profile. Null if you didn't supply one in the request.
metadata	object \| null	Yes	The metadata object you supplied in the request, returned unchanged. Null if you didn't supply one.
createdAt	string	Yes	ISO 8601 timestamp of when the profile was created.
updatedAt	string	Yes	ISO 8601 timestamp of the last time the profile was updated. Equal to createdAt on a fresh profile.

Status codes

201	The profile was created successfully and is returned in the response body.
400	The request body failed validation. Common causes include invalid JSON, a missing or too-long name, or a metadata field that isn't a JSON object.
401	The API key was missing or invalid.
402	You've hit the profile limit for your current plan. Upgrade to create more profiles.
409	The externalId you supplied is already in use by another profile in your account. Pick a different value or look up the existing profile instead.
500	Something failed on Synposter's side (a database lookup or write). Safe to retry.