cURL

curl -X POST \
  -H "Authorization: Bearer <access_token>" \
  -H "Idempotency-Key: <stable_request_key>" \
  -H "Content-Type: application/json" \
  -d '{"firstName":"Jane","email":"jane@example.com","assignedCoach":"<coachId>","inviteByEmail":true}' \
  https://api.fitsociety.io/public/v1/clients

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({firstName: 'Jane'})
};

fetch('https://api.fitsociety.io/public/v1/clients', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.fitsociety.io/public/v1/clients"

payload = { "firstName": "Jane" }
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "data": {
    "client": {
      "_id": "66f7b8b1e13c8d25f4d3d90c",
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane@example.com",
      "emailIsPlaceholder": false,
      "timeZone": "Europe/Amsterdam",
      "language": "nl"
    },
    "companyClientData": {
      "_id": "66f7b8b1e13c8d25f4d3d91c",
      "assignedCoach": "66f7b8b1e13c8d25f4d3d90a",
      "createdBy": "66f7b8b1e13c8d25f4d3d90a",
      "tags": [
        "string"
      ]
    },
    "inviteSent": false,
    "existingAccount": true,
    "notificationEmailSent": true
  },
  "meta": {
    "requestId": "4f849d7d-f4f1-45cc-b4b7-3984a3d17f83",
    "rateLimit": {
      "limit": 10,
      "remaining": 9,
      "resetSeconds": 1
    },
    "idempotency": {
      "replayed": false
    }
  }
}

Client records

Create a client in the company

Adds a client to the company authenticated by the Public API Bearer token (clients:write). An existing account matching the normalized email is linked immediately through the same flow as the coach app, without approval, and receives a notification email. Existing profile fields are preserved. An account already linked to the company returns 409. inviteByEmail sends an app and client-portal invitation only for a newly created account; use the invitation endpoint separately for an existing account. Provide an email or set hasNoEmail=true to generate a placeholder.

POST

/

public

/

v1

/

clients

cURL

curl -X POST \
  -H "Authorization: Bearer <access_token>" \
  -H "Idempotency-Key: <stable_request_key>" \
  -H "Content-Type: application/json" \
  -d '{"firstName":"Jane","email":"jane@example.com","assignedCoach":"<coachId>","inviteByEmail":true}' \
  https://api.fitsociety.io/public/v1/clients

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({firstName: 'Jane'})
};

fetch('https://api.fitsociety.io/public/v1/clients', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.fitsociety.io/public/v1/clients"

payload = { "firstName": "Jane" }
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "data": {
    "client": {
      "_id": "66f7b8b1e13c8d25f4d3d90c",
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane@example.com",
      "emailIsPlaceholder": false,
      "timeZone": "Europe/Amsterdam",
      "language": "nl"
    },
    "companyClientData": {
      "_id": "66f7b8b1e13c8d25f4d3d91c",
      "assignedCoach": "66f7b8b1e13c8d25f4d3d90a",
      "createdBy": "66f7b8b1e13c8d25f4d3d90a",
      "tags": [
        "string"
      ]
    },
    "inviteSent": false,
    "existingAccount": true,
    "notificationEmailSent": true
  },
  "meta": {
    "requestId": "4f849d7d-f4f1-45cc-b4b7-3984a3d17f83",
    "rateLimit": {
      "limit": 10,
      "remaining": 9,
      "resetSeconds": 1
    },
    "idempotency": {
      "replayed": false
    }
  }
}

Authorizations

Authorization

string

header

required

Public API access token issued by /public/v1/oauth/token. Example: Authorization: Bearer fspt_.... Each resource request rechecks the token company's current provider access. Disabling access blocks existing tokens with 403 auth.provider_unavailable.

Headers

Idempotency-Key

string

required

Required for Public API write requests. Reusing the same key with the same method, path, and body replays the stored successful response; reusing it with a different request returns 409 idempotency.conflict.

Required string length: 1 - 200

Example:

"booking-create-20260714-001"

Body

application/json

firstName

string

required

Example:

"Jane"

lastName

string

Example:

"Doe"

email

string<email>

Example:

"jane@example.com"

hasNoEmail

boolean

Example:

false

inviteByEmail

boolean

Example:

true

assignedCoach

string

Example:

"66f7b8b1e13c8d25f4d3d90a"

tags

string[]

language

string

Example:

"nl"

timeZone

string

Example:

"Europe/Amsterdam"

Response

Existing account linked directly to the company; notification email attempted

data

object

required

Show child attributes

meta

object

required

Show child attributes