Create a Patient Record — POST /patients

The Create Patient endpoint registers a new patient record in your clinic. On success, the API returns the full patient object with a generated UUID and timestamps. Only the patient’s name is required — all other fields are optional and can be added later via the Update Patient endpoint.

Endpoint

POST https://api.bydoctor.com.br/v1/patients

Authentication

Authorization: Bearer YOUR_API_KEY

Request Body

Send a JSON body with Content-Type: application/json.

string

required

Patient’s full name. Must be between 2 and 255 characters.

string

Contact phone number in E.164 format, e.g. +5511999999999. The leading + and country code are required.

string

Patient’s email address. Must be a valid RFC 5322 email format.

string

Brazilian individual taxpayer identifier. Must match the format 123.456.789-00 including punctuation. The CPF is validated for correct formatting and check digits, and must be unique within your clinic.

string

Patient’s date of birth in YYYY-MM-DD format, e.g. 1990-03-15. The date must be in the past.

string

Name of the patient’s health insurance plan, e.g. "Unimed" or "SulAmérica".

Before creating a new patient, consider searching for an existing record using GET /patients?search= with the patient’s CPF or phone number as the query. Using CPF or phone as a deduplication key helps you avoid creating duplicate profiles for the same individual — particularly important when patients book through multiple channels.

Response Fields (201 Created)

string

required

Newly assigned UUID for the patient record.

string

required

Identifier of the clinic the patient was registered under.

string

required

Patient’s full name as submitted.

string

CPF as submitted, or null if not provided.

string

Phone number as submitted, or null if not provided.

string

Email address as submitted, or null if not provided.

string

Date of birth as submitted, or null if not provided.

string

Health plan name as submitted, or null if not provided.

boolean

required

Defaults to false for newly created patients.

string

required

ISO 8601 UTC timestamp of record creation.

string

required

ISO 8601 UTC timestamp of last modification. Equal to created_at on a freshly created record.

Error Responses

Status	Code	Description
`400 Bad Request`	`invalid_cpf_format`	The `cpf` field does not match the expected format or fails check-digit validation.
`401 Unauthorized`	`unauthorized`	Your API key is missing or invalid.
`409 Conflict`	`cpf_already_exists`	Another patient in your clinic already has the same CPF.

Example Request

curl --request POST \
  --url "https://api.bydoctor.com.br/v1/patients" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Carlos Eduardo Lima",
    "phone": "+5511988887777",
    "email": "carlos.lima@email.com",
    "cpf": "123.456.789-09",
    "date_of_birth": "1988-07-22",
    "health_plan": "Unimed"
  }'

Example Response

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "clinic_id": "clinic_01HXZ9QWERTY",
  "name": "Carlos Eduardo Lima",
  "cpf": "123.456.789-09",
  "phone": "+5511988887777",
  "email": "carlos.lima@email.com",
  "date_of_birth": "1988-07-22",
  "health_plan": "Unimed",
  "whatsapp_opt_out": false,
  "created_at": "2025-01-20T13:45:00Z",
  "updated_at": "2025-01-20T13:45:00Z"
}

Appointments

Patients

Schedules & Availability

Payments

Webhooks

Create a Patient Record — POST /patients | ByDoctor API

Endpoint

Authentication

Request Body

Response Fields (201 Created)

Error Responses

Example Request

Example Response

​Endpoint

​Authentication

​Request Body

​Response Fields (201 Created)

​Error Responses

​Example Request

​Example Response

Endpoint

Authentication

Request Body

Response Fields (201 Created)

Error Responses

Example Request

Example Response