> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anivahealth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Profile

> Step-by-step guide to creating and updating patient profiles

Use this guide to create a patient profile and assign it to your profile group. Profiles are the starting point for scheduling appointments and triggering lab orders.

<Steps>
  <Step title="Get your profile group reference">
    Every profile must be assigned to a profile group that belongs to your partner account. The `profile_group` field accepts either the group's immutable UUID or its human-readable slug — UUID is preferred because it never changes and survives slug renames.

    If you don't know your profile group reference, contact Aniva to retrieve it. You cannot create profiles without a valid reference.
  </Step>

  <Step title="Create the profile">
    Send a `POST` request to `/api/v1/profiles` with the patient's demographic data.

    <Note>
      The `first_name` field accepts only latin characters (A–Z, a–z). Names with non-latin scripts must be transliterated before submission.
    </Note>

    <Note>
      If you omit `email`, Aniva auto-generates a placeholder email address for the profile. You can update it later with a `PATCH` request.
    </Note>

    <Tip>
      The `language` field controls the language Aniva uses when communicating with the patient — for example, appointment reminders and result notifications. Set it to match the patient's preferred language. Supported values are `en` (English), `de` (German), and `fi` (Finnish). Defaults to `en`.
    </Tip>

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request POST \
        --url https://anivahealth.com/api/v1/profiles \
        --header 'Content-Type: application/json' \
        --header 'x-api-key: YOUR_API_KEY' \
        --data '{
          "first_name": "Emma",
          "last_name": "Müller",
          "sex": 2,
          "date_of_birth": "1990-04-15",
          "profile_group": "my-clinic-group",
          "email": "emma.muller@example.com",
          "language": "de"
        }'
      ```

      ```javascript JavaScript theme={null}
      const response = await fetch('https://anivahealth.com/api/v1/profiles', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'x-api-key': 'YOUR_API_KEY',
        },
        body: JSON.stringify({
          first_name: 'Emma',
          last_name: 'Müller',
          sex: 2,
          date_of_birth: '1990-04-15',
          profile_group: 'my-clinic-group',
          email: 'emma.muller@example.com',
          language: 'de',
        }),
      });

      const profile = await response.json();
      ```
    </CodeGroup>

    A successful request returns `201 Created` with the new profile object:

    ```json theme={null}
    {
      "id": "a3f1c2e4-58b7-4d9e-b012-3c7f8a2e1d56",
      "handle": null,
      "first_name": "Emma",
      "last_name": "Müller",
      "email": "emma.muller@example.com",
      "phone": null,
      "sex": 2,
      "date_of_birth": "1990-04-15",
      "height": null,
      "weight": null,
      "language": "de",
      "created_at": "2026-04-01T09:14:22Z",
      "updated_at": null
    }
    ```

    Save the `id` — you'll need it to schedule appointments and update the profile.
  </Step>

  <Step title="Update the profile (optional)">
    Use `PATCH /api/v1/profiles/{id}` to update any profile fields after creation. All fields are optional — only include the fields you want to change.

    The following example adds a phone number and height:

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request PATCH \
        --url https://anivahealth.com/api/v1/profiles/a3f1c2e4-58b7-4d9e-b012-3c7f8a2e1d56 \
        --header 'Content-Type: application/json' \
        --header 'x-api-key: YOUR_API_KEY' \
        --data '{
          "phone": "+4915123456789",
          "height": 168.5
        }'
      ```

      ```javascript JavaScript theme={null}
      const response = await fetch(
        'https://anivahealth.com/api/v1/profiles/a3f1c2e4-58b7-4d9e-b012-3c7f8a2e1d56',
        {
          method: 'PATCH',
          headers: {
            'Content-Type': 'application/json',
            'x-api-key': 'YOUR_API_KEY',
          },
          body: JSON.stringify({
            phone: '+4915123456789',
            height: 168.5,
          }),
        }
      );

      const updated = await response.json();
      ```
    </CodeGroup>

    A successful request returns `200 OK` with the full updated profile object.
  </Step>
</Steps>

## Error handling

| Status            | Cause                                                                                                          | Resolution                                                                                 |
| ----------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `400 Bad Request` | A required field is missing, a value is out of range, or `date_of_birth` is not in the past.                   | Check the error response body for the specific validation message and correct the request. |
| `403 Forbidden`   | Your API key does not have access to this operation, or you do not have access to the specified profile group. | Contact Aniva to confirm your API key permissions and profile group access.                |
| `404 Not Found`   | The `profile_group` value does not match any profile group on your account (neither by UUID nor by slug).      | Verify the reference is correct. Contact Aniva if you are unsure of your UUID or slug.     |