curl -X PUT https://allomia.com/api/organization/3f6c1d2e-8a4b-4f7e-9c21-5b0d7e4a9f13/metadata \
-H "Authorization: Bearer sk-your-partner-key" \
-H "Content-Type: application/json" \
-d '{
"metadata": {
"emrSystem": "ClinicFlow",
"specialties": ["family medicine", "pediatrics"],
"acceptsNewPatients": true
}
}'
{
"id": "5d8e2a1c-7b4f-4c9d-a0e3-6f1b2d3c4e58",
"organizationId": "3f6c1d2e-8a4b-4f7e-9c21-5b0d7e4a9f13",
"version": 3,
"metadata": {
"emrSystem": "ClinicFlow",
"specialties": ["family medicine", "pediatrics"],
"acceptsNewPatients": true
},
"createdAt": "2026-09-14T15:20:41.502Z",
"createdBy": "8c2d4f6a-1b3e-4a5c-9d7f-0e2b4c6a8d19"
}
{
"error": "Schema validation failed",
"details": [
{
"instancePath": "",
"schemaPath": "#/required",
"keyword": "required",
"params": { "missingProperty": "emrSystem" },
"message": "must have required property 'emrSystem'"
},
{
"instancePath": "/specialties",
"schemaPath": "#/properties/specialties/type",
"keyword": "type",
"params": { "type": "array" },
"message": "must be array"
}
]
}
{
"error": "Invalid request body format",
"details": {
"name": "ZodError",
"message": "[\n {\n \"expected\": \"record\",\n \"code\": \"invalid_type\",\n \"path\": [\n \"metadata\"\n ],\n \"message\": \"Invalid input: expected record, received undefined\"\n }\n]"
}
}
Organizations (partner keys)
Update organization metadata
Replaces a clinic’s metadata after checking it against your integration’s JSON Schema.
PUT
/
api
/
organization
/
{id}
/
metadata
curl -X PUT https://allomia.com/api/organization/3f6c1d2e-8a4b-4f7e-9c21-5b0d7e4a9f13/metadata \
-H "Authorization: Bearer sk-your-partner-key" \
-H "Content-Type: application/json" \
-d '{
"metadata": {
"emrSystem": "ClinicFlow",
"specialties": ["family medicine", "pediatrics"],
"acceptsNewPatients": true
}
}'
{
"id": "5d8e2a1c-7b4f-4c9d-a0e3-6f1b2d3c4e58",
"organizationId": "3f6c1d2e-8a4b-4f7e-9c21-5b0d7e4a9f13",
"version": 3,
"metadata": {
"emrSystem": "ClinicFlow",
"specialties": ["family medicine", "pediatrics"],
"acceptsNewPatients": true
},
"createdAt": "2026-09-14T15:20:41.502Z",
"createdBy": "8c2d4f6a-1b3e-4a5c-9d7f-0e2b4c6a8d19"
}
{
"error": "Schema validation failed",
"details": [
{
"instancePath": "",
"schemaPath": "#/required",
"keyword": "required",
"params": { "missingProperty": "emrSystem" },
"message": "must have required property 'emrSystem'"
},
{
"instancePath": "/specialties",
"schemaPath": "#/properties/specialties/type",
"keyword": "type",
"params": { "type": "array" },
"message": "must be array"
}
]
}
{
"error": "Invalid request body format",
"details": {
"name": "ZodError",
"message": "[\n {\n \"expected\": \"record\",\n \"code\": \"invalid_type\",\n \"path\": [\n \"metadata\"\n ],\n \"message\": \"Invalid input: expected record, received undefined\"\n }\n]"
}
}
Replaces a clinic’s metadata with the object you send. Use it to keep AlloMia in step with the clinic’s information in your system.
Requires a partner key whose creator is the partner account owner or a Tenant Admin. See Authentication.
In
Before you start
This endpoint only works for a clinic that has a metadata record. A clinic has one when both of these are true:- AlloMia has set up an integration, with its JSON Schema, for your partner account. Ask AlloMia to set it up and to share the schema with you.
- The clinic was created with an
externalId, through Create organization or with the External ID field in the dashboard.
404. See Metadata.
What happens on each call
- AlloMia checks that
metadatais a JSON object. - It checks the object against your integration’s JSON Schema and reports every rule it breaks.
- If the object is valid, it replaces the clinic’s metadata (it doesn’t merge with the old object), adds 1 to
version, and marks the sync as successful. - It then refreshes the context of each of the clinic’s active agents.
Headers
Path parameters
The clinic’s organization ID. See Finding IDs.
Body
The clinic’s complete metadata, as a JSON object (not an array or a string). It must match your integration’s JSON Schema. Send every field you want to keep: fields you leave out are removed.
Response
Returns200 with the clinic’s metadata record.
When the metadata record was first created (with the clinic), ISO 8601 in UTC. It doesn’t change on updates.
Errors
| Status | Body | When |
|---|---|---|
400 | {"error": "Invalid request body format", "details": {...}} | metadata is missing or isn’t a JSON object. details.message holds the problems as a JSON-encoded string. |
400 | {"error": "Schema validation failed", "details": [...]} | The object breaks your integration’s JSON Schema. details lists every problem. See the example. |
400 | {"error": "Invalid JSON format in request body"} | The body isn’t valid JSON. |
401 | {"error": "Tenant ID is required"} | The key is a clinic key. Use a partner key. |
401 | {"error": "Unauthorized access"} | The key is missing, malformed, unknown or deleted. |
403 | {"error": "Insufficient permissions"} | The key’s creator isn’t the partner account owner or a Tenant Admin. |
404 | {"error": "Organization metadata not found"} | The clinic has no metadata record. See Before you start. |
404 | {"error": "Organization integration not found"} | The clinic isn’t linked to your integration. This is also what you get for invalid JSON sent for such a clinic. |
404 | {"error": "Integration provider not found"} | The integration behind the clinic is missing. Contact AlloMia. |
404 | {"error": "Organization not found"} | No clinic with this ID. |
429 | {"error": "Too many requests", "retryAfter": 60} | See Rate limits. |
500 | {"error": "An error occurred while updating metadata"} | Unexpected server error. Nothing was saved. |
details for a schema error, instancePath points to the field (empty for the top level), keyword names the rule, params gives specifics such as missingProperty, and message explains it.
See Errors for the full list.
curl -X PUT https://allomia.com/api/organization/3f6c1d2e-8a4b-4f7e-9c21-5b0d7e4a9f13/metadata \
-H "Authorization: Bearer sk-your-partner-key" \
-H "Content-Type: application/json" \
-d '{
"metadata": {
"emrSystem": "ClinicFlow",
"specialties": ["family medicine", "pediatrics"],
"acceptsNewPatients": true
}
}'
{
"id": "5d8e2a1c-7b4f-4c9d-a0e3-6f1b2d3c4e58",
"organizationId": "3f6c1d2e-8a4b-4f7e-9c21-5b0d7e4a9f13",
"version": 3,
"metadata": {
"emrSystem": "ClinicFlow",
"specialties": ["family medicine", "pediatrics"],
"acceptsNewPatients": true
},
"createdAt": "2026-09-14T15:20:41.502Z",
"createdBy": "8c2d4f6a-1b3e-4a5c-9d7f-0e2b4c6a8d19"
}
{
"error": "Schema validation failed",
"details": [
{
"instancePath": "",
"schemaPath": "#/required",
"keyword": "required",
"params": { "missingProperty": "emrSystem" },
"message": "must have required property 'emrSystem'"
},
{
"instancePath": "/specialties",
"schemaPath": "#/properties/specialties/type",
"keyword": "type",
"params": { "type": "array" },
"message": "must be array"
}
]
}
{
"error": "Invalid request body format",
"details": {
"name": "ZodError",
"message": "[\n {\n \"expected\": \"record\",\n \"code\": \"invalid_type\",\n \"path\": [\n \"metadata\"\n ],\n \"message\": \"Invalid input: expected record, received undefined\"\n }\n]"
}
}