Create patient

Use the organization gMedic account. No automatic write retries; reconcile an unknown outcome before repeating.

Scope: gmedic:patients:write
Credentials: an API key, a client-credentials token or a person's access token
Effect: writes; not idempotent: check the outcome before you retry
Limits: request body up to 32 KB, response up to 256 KB
CLI: arbol gmedic patients create · MCP tool: gmedic_patients_create

POST

https://api.getarbol.com/v1/gmedic/patients

Authorization

Authorization
string
required
Bearer <token>, where the token is an API key, a client-credentials token or a person's access token with the scope gmedic:patients:write. Get an API key.

Request body JSON required

data
object
required
- documentNumber
  string
  required
  maxLength: 255
- documentTypeId
  string
  required
  pattern: ^[1-9][0-9]{0,14}$
- sourceCountryCode
  optional
  string
  maxLength: 3 · minLength: 3
- expeditionPlaceCode
  optional
  string
  maxLength: 5 · minLength: 5
- givenName
  optional
  string
  maxLength: 255
- familyName
  optional
  string
  maxLength: 255
- email
  optional
  string
  maxLength: 255
- phone
  optional
  string
  maxLength: 255
- mobilePhone
  optional
  string
  maxLength: 255
- genderId
  optional
  string
  pattern: ^[1-9][0-9]{0,14}$
- birthDate
  optional
  string
  maxLength: 20000 · pattern: ^[0-9]{8}$
- address
  optional
  string
  maxLength: 255
- countryCode
  optional
  string
  maxLength: 3 · minLength: 3
- locationCode
  optional
  string
  maxLength: 5 · minLength: 5
- locationZoneTypeId
  optional
  string
  pattern: ^[1-9][0-9]{0,14}$
- educationLevelId
  optional
  string
  pattern: ^[1-9][0-9]{0,14}$
- profession
  optional
  string
  maxLength: 255
- maritalStatusId
  optional
  string
  pattern: ^[1-9][0-9]{0,14}$
- occupationId
  optional
  string
  pattern: ^[1-9][0-9]{0,14}$
- ethnicityId
  optional
  string
  pattern: ^[1-9][0-9]{0,14}$
- disabilityCategoryId
  optional
  string
  pattern: ^[1-9][0-9]{0,14}$
- householdCompositionTypeId
  optional
  string
  pattern: ^[1-9][0-9]{0,14}$
- householdSize
  optional
  integer
  maximum: 9007199254740991 · minimum: 0
- childrenCount
  optional
  integer
  maximum: 9007199254740991 · minimum: 0
- dependentsCount
  optional
  integer
  maximum: 9007199254740991 · minimum: 0
- socioeconomicStratum
  optional
  integer
  maximum: 9007199254740991 · minimum: 0
- epsId
  optional
  string
  pattern: ^[1-9][0-9]{0,14}$
- arlId
  optional
  string
  pattern: ^[1-9][0-9]{0,14}$
- afpId
  optional
  string
  pattern: ^[1-9][0-9]{0,14}$
- bloodTypeId
  optional
  string
  pattern: ^[1-9][0-9]{0,14}$
- healthRegimeId
  optional
  string
  pattern: ^[1-9][0-9]{0,14}$
- healthPartnerId
  optional
  string
  pattern: ^[1-9][0-9]{0,14}$
- healthPartnerIdNumber
  optional
  string
  maxLength: 255
- referredByTypeId
  optional
  string
  pattern: ^[1-9][0-9]{0,14}$
- referredByName
  optional
  string
  maxLength: 255
- contactPerson
  optional
  string
  maxLength: 255
- contactPersonPhone
  optional
  string
  maxLength: 255
- responsible
  optional
  string
  maxLength: 255
- responsiblePhone
  optional
  string
  maxLength: 255
- responsibleRelationship
  optional
  string
  maxLength: 255
- properties
  optional
  map of
  string
- firstName
  deprecated
  string
  Deprecated: use givenName. Answered until 2027-01-28.
  
  maxLength: 255
- lastName
  deprecated
  string
  Deprecated: use familyName. Answered until 2027-01-28.
  
  maxLength: 255
- mobile
  deprecated
  string
  Deprecated: use mobilePhone. Answered until 2027-01-28.
  
  maxLength: 255
}
connectionId
optional
string
pattern: ^con_[0-9A-Za-z]{26}$

Returns

200

Successful operation.

JSON

success
true
required
data
object
required
- id
  string
  required
  pattern: ^[1-9][0-9]{0,14}$
- key
  optional
  string | null
  maxLength: 20000
- createdAt
  optional
  string | null
  maxLength: 20000
- updatedAt
  optional
  string | null
  maxLength: 20000
- documentNumber
  optional
  string | null
  maxLength: 20000
- documentType
  optional
  object | null
  id
  string
  required
  pattern: ^[1-9][0-9]{0,14}$
  name
  optional
  string | null
  maxLength: 20000
  label
  optional
  string | null
  maxLength: 20000
  value
  optional
  string | null
  maxLength: 20000
- givenName
  optional
  string | null
  maxLength: 20000
- familyName
  optional
  string | null
  maxLength: 20000
- healthCompanyName
  optional
  string | null
  maxLength: 20000
- birthDate
  optional
  string | null
  maxLength: 20000
- ageInYears
  optional
  integer | null
  maximum: 9007199254740991 · minimum: 0
- ageMonths
  optional
  integer | null
  maximum: 9007199254740991 · minimum: 0
- birthdayDays
  optional
  integer | null
  maximum: 9007199254740991 · minimum: 0
- email
  optional
  string | null
  maxLength: 20000
- phone
  optional
  string | null
  maxLength: 20000
- mobilePhone
  optional
  string | null
  maxLength: 20000
- address
  optional
  string | null
  maxLength: 20000
- location
  optional
  string | null
  maxLength: 20000
- gender
  optional
  object | null
  id
  string
  required
  pattern: ^[1-9][0-9]{0,14}$
  name
  optional
  string | null
  maxLength: 20000
  label
  optional
  string | null
  maxLength: 20000
  value
  optional
  string | null
  maxLength: 20000
- genderIdentity
  optional
  object | null
  id
  string
  required
  pattern: ^[1-9][0-9]{0,14}$
  name
  optional
  string | null
  maxLength: 20000
  label
  optional
  string | null
  maxLength: 20000
  value
  optional
  string | null
  maxLength: 20000
- contactPerson
  optional
  string | null
  maxLength: 20000
- contactPersonPhone
  optional
  string | null
  maxLength: 20000
- responsible
  optional
  string | null
  maxLength: 20000
- responsiblePhone
  optional
  string | null
  maxLength: 20000
- responsibleRelationship
  optional
  string | null
  maxLength: 20000
- healthRegime
  optional
  object | null
  id
  string
  required
  pattern: ^[1-9][0-9]{0,14}$
  name
  optional
  string | null
  maxLength: 20000
  label
  optional
  string | null
  maxLength: 20000
  value
  optional
  string | null
  maxLength: 20000
- jobCompany
  optional
  string | null
  maxLength: 20000
- referredBy
  optional
  object | null
  id
  string
  required
  pattern: ^[1-9][0-9]{0,14}$
  name
  optional
  string | null
  maxLength: 20000
  label
  optional
  string | null
  maxLength: 20000
  value
  optional
  string | null
  maxLength: 20000
- referredByName
  optional
  string | null
  maxLength: 20000
- status
  optional
  object | null
  id
  string
  required
  pattern: ^[1-9][0-9]{0,14}$
  name
  optional
  string | null
  maxLength: 20000
  label
  optional
  string | null
  maxLength: 20000
  value
  optional
  string | null
  maxLength: 20000
- category
  optional
  object | null
  id
  string
  required
  pattern: ^[1-9][0-9]{0,14}$
  name
  optional
  string | null
  maxLength: 20000
  label
  optional
  string | null
  maxLength: 20000
  value
  optional
  string | null
  maxLength: 20000
- patientType
  optional
  object | null
  id
  string
  required
  pattern: ^[1-9][0-9]{0,14}$
  name
  optional
  string | null
  maxLength: 20000
  label
  optional
  string | null
  maxLength: 20000
  value
  optional
  string | null
  maxLength: 20000
- educationLevel
  optional
  object | null
  id
  string
  required
  pattern: ^[1-9][0-9]{0,14}$
  name
  optional
  string | null
  maxLength: 20000
  label
  optional
  string | null
  maxLength: 20000
  value
  optional
  string | null
  maxLength: 20000
- profession
  optional
  string | null
  maxLength: 20000
- occupation
  optional
  string | null
  maxLength: 20000
- maritalStatus
  optional
  object | null
  id
  string
  required
  pattern: ^[1-9][0-9]{0,14}$
  name
  optional
  string | null
  maxLength: 20000
  label
  optional
  string | null
  maxLength: 20000
  value
  optional
  string | null
  maxLength: 20000
- ethnicity
  optional
  object | null
  id
  string
  required
  pattern: ^[1-9][0-9]{0,14}$
  name
  optional
  string | null
  maxLength: 20000
  label
  optional
  string | null
  maxLength: 20000
  value
  optional
  string | null
  maxLength: 20000
- disabilityCategory
  optional
  object | null
  id
  string
  required
  pattern: ^[1-9][0-9]{0,14}$
  name
  optional
  string | null
  maxLength: 20000
  label
  optional
  string | null
  maxLength: 20000
  value
  optional
  string | null
  maxLength: 20000
- householdCompositionType
  optional
  object | null
  id
  string
  required
  pattern: ^[1-9][0-9]{0,14}$
  name
  optional
  string | null
  maxLength: 20000
  label
  optional
  string | null
  maxLength: 20000
  value
  optional
  string | null
  maxLength: 20000
- householdSize
  optional
  integer | null
  maximum: 9007199254740991 · minimum: 0
- childrenCount
  optional
  integer | null
  maximum: 9007199254740991 · minimum: 0
- dependentsCount
  optional
  integer | null
  maximum: 9007199254740991 · minimum: 0
- socioeconomicStratum
  optional
  integer | null
  maximum: 9007199254740991 · minimum: 0
- eps
  optional
  string | null
  maxLength: 20000
- arl
  optional
  string | null
  maxLength: 20000
- afp
  optional
  object | null
  id
  string
  required
  pattern: ^[1-9][0-9]{0,14}$
  name
  optional
  string | null
  maxLength: 20000
  label
  optional
  string | null
  maxLength: 20000
  value
  optional
  string | null
  maxLength: 20000
- properties
  optional
  object | null
- creationDate
  deprecated
  string | null
  Deprecated: use createdAt. Answered until 2027-01-28.
  
  maxLength: 20000
- modificationDate
  deprecated
  string | null
  Deprecated: use updatedAt. Answered until 2027-01-28.
  
  maxLength: 20000
- firstName
  deprecated
  string | null
  Deprecated: use givenName. Answered until 2027-01-28.
  
  maxLength: 20000
- lastName
  deprecated
  string | null
  Deprecated: use familyName. Answered until 2027-01-28.
  
  maxLength: 20000
- mobile
  deprecated
  string | null
  Deprecated: use mobilePhone. Answered until 2027-01-28.
  
  maxLength: 20000
- state
  deprecated
  object | null
  Deprecated: use status. Answered until 2027-01-28.
  
  id
  string
  required
  pattern: ^[1-9][0-9]{0,14}$
  name
  optional
  string | null
  maxLength: 20000
  label
  optional
  string | null
  maxLength: 20000
  value
  optional
  string | null
  maxLength: 20000
}
error
unknown
required
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

400

INVALID_INPUT: The request does not match the published schema.

JSON

success
false
required
data
unknown
required
error
object
required
The request does not match the published schema.
- code
  INVALID_INPUT
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  issues
  optional
  array of
  object
  path
  string
  required
  RFC 6901 JSON Pointer to the refused field; empty for the whole input.
  
  maxLength: 256
  message
  string
  required
  maxLength: 256
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

401

UNAUTHORIZED: A valid access token is required.

JSON

success
false
required
data
unknown
required
error
object
required
A valid access token is required.
- code
  UNAUTHORIZED
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

403

FORBIDDEN: The token does not authorize this operation.

JSON

success
false
required
data
unknown
required
error
object
required
The token does not authorize this operation.
- code
  FORBIDDEN
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

404

CONNECTION_NOT_FOUND: This organization has no gMedic connection with this id.
RECORD_NOT_FOUND: gMedic has no record with one of the ids sent.

JSON

success
false
required
data
unknown
required
error
required
One of the following:
GmedicConnectionNotFoundFailure
CONNECTION_NOT_FOUND
code
CONNECTION_NOT_FOUND
required
The failure code, stable across releases.

message
string
required
What went wrong, for people; it never contains input values.

retryable
false
required
Whether repeating the same request may succeed.

data
object
required
No fields.

GmedicRecordNotFoundFailure
RECORD_NOT_FOUND
code
RECORD_NOT_FOUND
required
The failure code, stable across releases.

message
string
required
What went wrong, for people; it never contains input values.

retryable
false
required
Whether repeating the same request may succeed.

data
object
required
No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

409

NOT_CONFIGURED: This organization has no verified gMedic connection.

JSON

success
false
required
data
unknown
required
error
object
required
This organization has no verified gMedic connection.
- code
  NOT_CONFIGURED
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

413

REQUEST_TOO_LARGE: The request exceeds the allowed size.

JSON

success
false
required
data
unknown
required
error
object
required
The request exceeds the allowed size.
- code
  REQUEST_TOO_LARGE
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

415

UNSUPPORTED_MEDIA_TYPE: The request content type is not supported.

JSON

success
false
required
data
unknown
required
error
object
required
The request content type is not supported.
- code
  UNSUPPORTED_MEDIA_TYPE
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

422

PROVIDER_INPUT_REJECTED: gMedic rejected the supplied fields.

JSON

success
false
required
data
unknown
required
error
object
required
gMedic rejected the supplied fields.
- code
  PROVIDER_INPUT_REJECTED
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

429

RATE_LIMITED: The request rate limit was exceeded. Try again later.

JSON

success
false
required
data
unknown
required
error
object
required
The request rate limit was exceeded. Try again later.
- code
  RATE_LIMITED
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  true
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

500

INTERNAL_ERROR: The service could not complete the operation.

JSON

success
false
required
data
unknown
required
error
object
required
The service could not complete the operation.
- code
  INTERNAL_ERROR
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  false
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

502

OUTCOME_UNKNOWN: The operation may have been applied; check its result before repeating it.
PROVIDER_ACCESS_REJECTED: The configured gMedic account did not authorize this operation.
PROVIDER_RESPONSE_INVALID: gMedic returned an unexpected response.

JSON

success
false
required
data
unknown
required
error
required
One of the following:
OutcomeUnknownFailure
OUTCOME_UNKNOWN
code
OUTCOME_UNKNOWN
required
The failure code, stable across releases.

message
string
required
What went wrong, for people; it never contains input values.

retryable
false
required
Whether repeating the same request may succeed.

data
object
required
No fields.

GmedicProviderAccessRejectedFailure
PROVIDER_ACCESS_REJECTED
code
PROVIDER_ACCESS_REJECTED
required
The failure code, stable across releases.

message
string
required
What went wrong, for people; it never contains input values.

retryable
false
required
Whether repeating the same request may succeed.

data
object
required
No fields.

GmedicProviderResponseInvalidFailure
PROVIDER_RESPONSE_INVALID
code
PROVIDER_RESPONSE_INVALID
required
The failure code, stable across releases.

message
string
required
What went wrong, for people; it never contains input values.

retryable
false
required
Whether repeating the same request may succeed.

data
object
required
No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

503

UPSTREAM_UNAVAILABLE: The upstream service could not complete the request.
CATALOG_SEARCH_INCOMPLETE: The service catalog search could not be completed within its limits. Service absence cannot be concluded.
PROVIDER_UNAVAILABLE: gMedic is temporarily unavailable.

JSON

success
false
required
data
unknown
required
error
required
One of the following:
UpstreamUnavailableFailure
UPSTREAM_UNAVAILABLE
code
UPSTREAM_UNAVAILABLE
required
The failure code, stable across releases.

message
string
required
What went wrong, for people; it never contains input values.

retryable
true
required
Whether repeating the same request may succeed.

data
object
required
No fields.

GmedicCatalogSearchIncompleteFailure
CATALOG_SEARCH_INCOMPLETE
code
CATALOG_SEARCH_INCOMPLETE
required
The failure code, stable across releases.

message
string
required
What went wrong, for people; it never contains input values.

retryable
false
required
Whether repeating the same request may succeed.

data
object
required
No fields.

GmedicProviderUnavailableFailure
PROVIDER_UNAVAILABLE
code
PROVIDER_UNAVAILABLE
required
The failure code, stable across releases.

message
string
required
What went wrong, for people; it never contains input values.

retryable
true
required
Whether repeating the same request may succeed.

data
object
required
No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}

504

UPSTREAM_TIMEOUT: The upstream service did not respond before its deadline.

JSON

success
false
required
data
unknown
required
error
object
required
The upstream service did not respond before its deadline.
- code
  UPSTREAM_TIMEOUT
  required
  The failure code, stable across releases.
- message
  string
  required
  What went wrong, for people; it never contains input values.
- retryable
  true
  required
  Whether repeating the same request may succeed.
- data
  object
  required
  No fields.
}
metadata
object
required
What every answer carries besides its data or error.
- requestId
  string
  required
  Request correlation identifier, also sent as X-Request-Id.
}