Care MCP

POST /api/org/clients

A client under the organisation's own reference, with what the rules need. No sign-in of their own.

Surface: organisation. Who may call: organisation-key. Key: organisation.clients.create.

Example request

curl -X POST https://caremcp.com/api/org/clients \
  -H "Authorization: Bearer <API key or session>" \
  -H "Content-Type: application/json" \
  -d '{"externalRef":"user-8842","birthDate":"1984-03-12","location":{"country":"DE"},"language":"de","healthConsent":true}'

Example input

{
  "externalRef": "user-8842",
  "birthDate": "1984-03-12",
  "location": {
    "country": "DE"
  },
  "language": "de",
  "healthConsent": true
}

Input schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "externalRef": {
   "type": "string",
   "minLength": 1,
   "maxLength": 120,
   "description": "The organisation's own id for the client, unique within the organisation."
  },
  "birthDate": {
   "type": "string",
   "format": "date",
   "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
  },
  "location": {
   "type": "object",
   "properties": {
    "country": {
     "type": "string",
     "pattern": "^[A-Z]{2}$"
    },
    "region": {
     "type": "string",
     "pattern": "^[A-Z0-9]{1,3}$"
    }
   },
   "required": [
    "country"
   ]
  },
  "language": {
   "type": "string",
   "pattern": "^[a-z]{2}(-[A-Z]{2})?$"
  },
  "healthConsent": {
   "type": "boolean",
   "const": true,
   "description": "The organisation has obtained the client's explicit consent to the Health data notice (version 2026-09-24) and holds the record."
  }
 },
 "required": [
  "externalRef",
  "birthDate",
  "location",
  "language",
  "healthConsent"
 ]
}

Output schema

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "id": {
   "type": "string"
  },
  "email": {
   "type": [
    "string",
    "null"
   ]
  },
  "birthDate": {
   "type": "string",
   "format": "date",
   "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
  },
  "location": {
   "type": "object",
   "properties": {
    "country": {
     "type": "string",
     "pattern": "^[A-Z]{2}$"
    },
    "region": {
     "type": "string",
     "pattern": "^[A-Z0-9]{1,3}$"
    }
   },
   "required": [
    "country"
   ],
   "additionalProperties": false
  },
  "language": {
   "type": "string",
   "pattern": "^[a-z]{2}(-[A-Z]{2})?$"
  },
  "currency": {
   "type": "string",
   "enum": [
    "USD",
    "EUR"
   ]
  },
  "healthConsent": {
   "anyOf": [
    {
     "type": "object",
     "properties": {
      "version": {
       "type": "string"
      },
      "at": {
       "type": "string"
      }
     },
     "required": [
      "version",
      "at"
     ],
     "additionalProperties": false
    },
    {
     "type": "null"
    }
   ]
  },
  "organisationId": {
   "type": [
    "string",
    "null"
   ]
  },
  "createdAt": {
   "type": "string"
  },
  "externalRef": {
   "type": "string"
  }
 },
 "required": [
  "id",
  "email",
  "birthDate",
  "location",
  "language",
  "currency",
  "healthConsent",
  "organisationId",
  "createdAt",
  "externalRef"
 ],
 "additionalProperties": false
}