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

# Create or update a contact

> Create a contact by email, or update it, apply existing tags and record a consent you collected

**Phone numbers.** A number that starts with `+` and a country code keeps that country. A Korean mobile number without a country code, such as `010-2938-4756`, is saved as a Korean (+82) number. There is no country field, so write numbers from other countries with their `+` country code.

**First seen date.** Send `firstSeenAt` (RFC 3339, not in the future, 2000-01-01 or later) to set the date the contact is shown as first seen, for example the day the person joined your service. It applies to a new contact and to an existing one, and it replaces the stored date every time you send it. Leave it out to keep the date as it is.


## OpenAPI

````yaml api-reference/openapi.yaml POST /api/preview/contacts
openapi: 3.1.0
info:
  title: DocuRise Public API
  version: preview
  description: >
    Programmatic access to DocuRise.


    **This is a preview API.** Every path is versioned under `/api/preview/`

    and carries no compatibility guarantee while it is in preview: fields,

    values and error codes may be added, changed or removed. Once the

    contract stabilizes it will be promoted to `/api/v1/`. See the

    [changelog](/changelog) for what changed and when.


    ### Access


    Every route requires:

    1. A valid API key (see Authentication below).

    2. The calling account's plan must be **Iconic or above**.

    3. During the preview the API is available to some accounts only, whatever
       the plan. Accounts without access get a `404` from every route below; if
       you expect access, check with your DocuRise contact.

    Generate and manage keys from **Settings → Developers** in the dashboard.


    ### Idempotency


    `POST` endpoints that create a resource require an `Idempotency-Key`

    header. Reusing the same key with the same request body replays the

    original response (same status code, same body) instead of creating a

    second resource — safe to retry on timeout or connection loss. A key is

    remembered for 7 days; after that the same key is treated as a new

    request. Reusing the same key with a **different** body is rejected with

    `IDEMPOTENCY_KEY_CONFLICT`. Generate a fresh key (a UUID or ULID is fine)

    per logical operation, not per HTTP attempt.


    One exception: `POST /api/preview/tags` takes no `Idempotency-Key`. Creating
    the same

    tag name twice changes nothing (the second call returns the existing tag
    with

    `created: false`), so a retry is always safe.


    Another exception: `POST /api/preview/segments/preview` takes no
    `Idempotency-Key`.

    It saves nothing, so repeating it is always safe.


    ### Response compatibility


    Responses may gain additional fields over time, and `type`/`code`-style

    enum values (for example a future `LeadFormQuestion.type` member, or a

    new error `code`) may gain new members. Always ignore fields and enum

    values you don't recognize rather than treating them as errors — this is

    what makes every additive change under `preview` non-breaking.


    A field absent from a response is not always the same as a field present

    with value `null`. A field whose type never includes `null` is omitted

    when it doesn't apply — it is never sent as `null` (for example,

    `retryAfterSeconds` is left out entirely when there's no backoff hint, not

    set to `null`). A field whose type explicitly allows `null` uses it to

    mean something real and distinct from "not present" (for example,

    `expiresAt: null` on a document means it has no fixed expiry date, not

    "unknown" or "not applicable").


    All field names use `camelCase` — `notionUrl`, `leadFormQuestions`,

    `collectName`, and so on — consistently across every request and

    response body.


    ### Identifiers


    `id` values are opaque strings. Store and compare them as unstructured

    tokens — don't parse them, validate their format, or assume anything

    about their length or character set.


    ### Errors


    Every error response has the same shape:


    ```json

    { "error": { "code": "STRING", "message": "human-readable", "retryable":
    false } }

    ```


    Switch on `code`, not `message` — `message` is free text for logs/debugging

    and may be reworded without notice; `code` is the stable contract.
    `retryable`

    tells you whether the same request is safe to retry as-is; when present,

    `retryAfterSeconds` is a concrete backoff hint.


    A request body that contains text the database cannot store is refused with

    `400 VALIDATION_ERROR` before anything is saved: a NUL character (`\u0000`)

    or an unpaired surrogate (half of an emoji, left behind when a string is cut

    between two UTF-16 units), in a string value or in a property name. Whole

    emoji and all other characters are accepted. `message` names the field and

    never repeats the text.


    ### Rate limiting


    60 requests/minute per account across all `/api/preview/*` routes,

    regardless of how many keys that account has. Exceeding it returns `429`

    with a `Retry-After` header.


    Separately, an account can have at most 10 requests running at the same

    moment across these routes, however many keys it has. A request that would

    be the eleventh returns `429` with `code: TOO_MANY_CONCURRENT_REQUESTS` and

    `Retry-After: 1`; wait for one of your requests to finish and retry. This

    limit counts requests that have not finished, so it can apply even while

    you are under 60 requests per minute.
  contact:
    name: DocuRise
    url: https://docurise.io
servers:
  - url: https://docurise.io
    description: Production
security:
  - apiKey: []
tags:
  - name: Documents
    description: >-
      Create documents (a Notion page, a post or a lead-capture form), list or
      read the documents you own, publish drafts, change their status, expiry
      and email protection, and edit their title, description, post body, and
      form fields and questions.
  - name: Analytics
    description: >-
      Read aggregate view, visitor, lead and conversion numbers for one of your
      documents, split by traffic channel, compared with the previous period, or
      as a form funnel, and rank all of your documents by views, visitors or
      leads.
  - name: Folders
    description: Read your folders and courses, with item counts.
  - name: Products
    description: Read your product catalog (read-only).
  - name: Audiences
    description: >-
      List your tags and groups with contact counts, create a group from a rule,
      count who a rule would match, and read one group with its rule. Counts
      only; no member data is ever returned.
  - name: Contacts
    description: >-
      Add or remove a tag on one of your contacts. Contact details are never
      returned.
  - name: Email
    description: >-
      Read email broadcasts, their aggregate delivery numbers, and automations.
      Email only; Kakao is not included.
  - name: Instagram
    description: >-
      Create, read, edit, pause and resume Instagram comment-to-DM automation
      rules.
  - name: Account
    description: Inspect the API key you are calling with.
paths:
  /api/preview/contacts:
    post:
      tags:
        - Contacts
      summary: Create or update a contact
      description: >
        Creates the contact for an email address in your account, or updates it
        if it

        exists, and can apply tags you already have and record a marketing
        consent you

        collected. Requires the `contacts:write` scope, which is offered only on
        the

        Business plan: on another plan the call returns `403 PLAN_REQUIRED`. A
        key

        created before this scope existed does not have it: add it with **Edit

        scopes** under Settings → Developers (the key itself does not change).


        The call answers `201` when it created the contact and `200` when the
        contact

        already existed, and the body says which (`created`). It sends no email
        by

        itself.


        **What an update changes.** A field you leave out, send as `null` or
        send as an

        empty string is left alone: nothing is ever cleared through this call. A

        non-empty `name`, `company` or `phone` replaces the stored value. The
        contact's

        last-activity time is not touched, because an API call is not a visit.
        Contacts

        are matched on their **current** address only: an address a contact used
        to have

        creates a new contact.


        **First seen.** `firstSeenAt` (RFC 3339, not in the future, 2000-01-01
        or later) sets

        the date the contact is shown as first seen, for a new contact and for
        an existing

        one, so you can bring in the day a person really joined your service. It
        replaces the

        stored date every time you send it; leave it out to keep the date as it
        is.


        **Tags.** `tags` takes up to 10 names of tags you already have (exact
        name, then

        its NFC form). If any name does not exist the call returns

        `422 TAG_NOT_FOUND` listing them and writes nothing, so a typo can never
        create

        a tag that a group rule later matches. Create tags with `POST
        /api/preview/tags`.


        **Consent is yours to attest, and it only goes up.** Without `consent`,
        a new

        contact has no marketing consent. `consent.marketing: true` needs

        `consent.collectedAt` (RFC 3339, not in the future) and `consent.source`
        (1-96

        characters, a label for where you collected it); without both the call
        returns

        `422 CONSENT_EVIDENCE_REQUIRED`. DocuRise records what you sent and the
        key

        that sent it; you are responsible for the consent being real. An
        existing

        contact can go from not consented to consented, never back, and the
        first

        consent record is kept. A contact your account holds as imported
        **without**

        consent (for example from a CSV import) becomes eligible for marketing
        messages

        once this call records its consent, so send `marketing: true` only for
        people who

        really agreed. A contact who unsubscribed, or whose address bounced or

        complained, is never changed by this call: `marketingConsent` in the
        response is

        the **stored** value, so `false` after you sent `marketing: true` means
        it was not

        applied. This call never unsubscribes or resubscribes anyone.


        **Groups and automations.** The contact's group membership is brought up
        to date

        shortly after the call, in the next scheduled run (within about 5
        minutes), not

        during it. After that run a group whose rule is "has tag X" includes the
        contact,

        and an automation that starts when a contact **enters a group** starts
        in the same

        run. Many calls in one interval are handled together. Two things to
        know. A group whose rule says

        the contact has **not** viewed or answered something matches every
        contact made

        this way, because it has no visits. And an automation with "Require
        marketing

        consent" turned **off** (a service message) is sent to a contact who
        never

        consented, as long as they have not unsubscribed, so use it only for
        messages

        everyone should get. Contacts beyond your plan's lead limit are still
        created and

        are shown as locked in the dashboard.


        **`Idempotency-Key` is required.** The same key with the same body
        returns the

        first response (including `201` and `created: true`), so a retry after a

        timeout never changes the answer. A refused request is remembered with
        its key:

        after fixing the cause (for example creating the missing tag) send a new
        key.
      operationId: upsertContact
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          description: >-
            A unique client-generated string (≤ 255 characters) identifying this
            attempt. See "Idempotency" above.
          schema:
            type: string
            maxLength: 255
          example: 550e8400-e29b-41d4-a716-446655440000
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertContactRequest'
      responses:
        '200':
          description: >-
            The contact already existed and was updated with what you sent
            (`created: false`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertedContact'
              example:
                id: 3b9f6c52-0f0e-4f3a-9a52-1c1d7e0a8f10
                email: person@example.com
                created: false
                marketingConsent: true
                tags:
                  - signed-up
        '201':
          description: The contact was created by this call.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertedContact'
              example:
                id: 3b9f6c52-0f0e-4f3a-9a52-1c1d7e0a8f10
                email: person@example.com
                created: true
                marketingConsent: false
                tags:
                  - signed-up
        '400':
          description: >-
            `INVALID_JSON` (the body is not JSON) or `VALIDATION_ERROR` (`email`
            missing or not a valid address, a field over its length, more than
            10 tags, `consent` malformed or `consent.collectedAt` not RFC 3339
            with an offset, `firstSeenAt` not RFC 3339 with an offset, in the
            future or before 2000, a NUL character, or an unknown field).
            Nothing was written.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            `PAST_DUE_RESTRICTED`, `INSUFFICIENT_SCOPE` (the key lacks
            `contacts:write`) or `PLAN_REQUIRED` (your plan does not include
            this endpoint).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          $ref: '#/components/responses/NotOnAllowlist'
        '409':
          description: >
            `IDEMPOTENCY_KEY_CONFLICT` (not retryable: the same key was already
            used

            with a different body; use a new key) or
            `IDEMPOTENCY_KEY_IN_PROGRESS`

            (retryable: a request with this key is still being processed;

            `retryAfterSeconds` suggests a backoff).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: >
            The request is well-formed but cannot be applied. Nothing was
            written. Not retryable as is.

            `TAG_NOT_FOUND`: one or more `tags` do not exist in your account;
            `details.tags` lists them.

            `CONSENT_EVIDENCE_REQUIRED`: `consent.marketing` is `true` without a
            past `collectedAt` and a `source`; `details.problems` lists what is
            missing or wrong.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                tagNotFound:
                  value:
                    error:
                      code: TAG_NOT_FOUND
                      message: >-
                        One or more tags do not exist. Nothing was written.
                        Create them with POST /tags.
                      retryable: false
                      details:
                        tags:
                          - sigend-up
                consentEvidenceRequired:
                  value:
                    error:
                      code: CONSENT_EVIDENCE_REQUIRED
                      message: >-
                        consent.marketing true needs consent.collectedAt (a past
                        RFC 3339 time) and consent.source
                      retryable: false
                      details:
                        problems:
                          - source_required
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          description: >-
            `INTERNAL_ERROR` (retryable). Something failed on our side; the
            cause is not echoed. Retry with the same `Idempotency-Key`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          $ref: '#/components/responses/Unavailable'
      security:
        - apiKey: []
      x-codeSamples:
        - lang: bash
          label: curl
          source: |
            curl -X POST 'https://docurise.io/api/preview/contacts' \
              -H 'Authorization: Bearer dr_live_<keyId>_<secret>' \
              -H 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
              -H 'Content-Type: application/json' \
              -d '{
                "email": "person@example.com",
                "name": "Ada Lee",
                "firstSeenAt": "2025-12-24T01:02:03Z",
                "tags": ["signed-up"],
                "consent": {
                  "marketing": true,
                  "collectedAt": "2026-11-09T01:02:03Z",
                  "source": "signup-form-v3"
                }
              }'
components:
  schemas:
    UpsertContactRequest:
      type: object
      required:
        - email
      additionalProperties: false
      properties:
        email:
          type: string
          maxLength: 320
          description: >-
            The contact's email address. Surrounding spaces are removed and
            letters lower-cased; it must be a plain ASCII address.
          example: person@example.com
        name:
          type:
            - string
            - 'null'
          maxLength: 200
          description: >-
            Replaces the stored name when non-empty. Omitted, `null` or empty
            leaves it alone.
          example: Ada Lee
        company:
          type:
            - string
            - 'null'
          maxLength: 200
          description: >-
            Replaces the stored company when non-empty. Omitted, `null` or empty
            leaves it alone.
          example: Example Inc
        phone:
          type:
            - string
            - 'null'
          maxLength: 32
          description: >-
            Replaces the stored phone when non-empty. A number that starts with
            `+` and a country code keeps that country. A Korean mobile number
            without a country code, such as `010-2938-4756`, is saved as a
            Korean (+82) number; there is no country field, so write any other
            country's number with its `+` country code. A number that cannot be
            parsed is kept as you sent it. Omitted, `null` or empty leaves it
            alone.
          example: +82 10 2938 4756
        firstSeenAt:
          type: string
          format: date-time
          description: >-
            The date the contact is shown as first seen, for example the day the
            person joined your service: RFC 3339 with an offset or `Z`, not in
            the future, 2000-01-01 or later. Replaces the stored date for a new
            and for an existing contact. Omitted leaves it alone (a new contact
            then gets the time of this call).
          example: '2025-12-24T01:02:03Z'
        tags:
          type: array
          maxItems: 10
          items:
            type: string
          description: >-
            Names of tags you already have, at most 10. Any name that does not
            exist is `422 TAG_NOT_FOUND` and nothing is written.
          example:
            - signed-up
        consent:
          type: object
          required:
            - marketing
          additionalProperties: false
          description: A marketing consent you collected. Omit it to give none.
          properties:
            marketing:
              type: boolean
              description: >-
                `true` records consent and then requires `collectedAt` and
                `source`. `false` records nothing and never withdraws a consent.
            collectedAt:
              type: string
              format: date-time
              description: >-
                When the person consented: RFC 3339 with an offset or `Z`, not
                in the future.
              example: '2026-11-09T01:02:03Z'
            source:
              type: string
              maxLength: 96
              description: A label for where you collected the consent (your form or flow).
              example: signup-form-v3
    UpsertedContact:
      type: object
      required:
        - id
        - email
        - created
        - marketingConsent
        - tags
      properties:
        id:
          type: string
          format: uuid
          description: The contact's id.
        email:
          type: string
          description: The address as stored (trimmed, lower-cased).
        created:
          type: boolean
          description: >-
            `true` if this call created the contact, `false` if it already
            existed.
        marketingConsent:
          type: boolean
          description: >-
            The marketing consent the contact has **now**. `false` after you
            sent `marketing: true` means it was not applied (the contact had
            unsubscribed or its address is suppressed).
        tags:
          type: array
          items:
            type: string
          description: >-
            The tags this call applied, by stored name. Each one is on the
            contact now.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - retryable
          properties:
            code:
              type: string
              description: >-
                Stable machine-readable error code — switch on this, not
                `message`.
            message:
              type: string
              description: Human-readable detail. May change wording without notice.
            retryable:
              type: boolean
              description: Whether retrying the identical request may succeed.
            retryAfterSeconds:
              type: integer
              description: Present only when a concrete backoff hint applies.
            details:
              type: object
              description: >
                Present only for a few specific codes:

                - `PROTECTION_RULE_CONFLICT`: `{ rule: string }`, the protection
                rule that refused the request
                  (`form`, `restricted_access`, `paid_lead_gate`, `free_lead_gate`, `form_no_access_controls`
                  or `needs_email_gate`).
                  Open-ended: tolerate new values.
                - `NEXT_POST_RULE_EXISTS`: `{ ruleId: string }`, the existing
                next-post rule.

                - `NOTION_FETCH_FAILED`: `{ notionErrorCode: string }`, one of
                  `NOTION_ERROR_PRIVATE`, `NOTION_ERROR_NOT_FOUND`,
                  `NOTION_ERROR_NETWORK`, `NOTION_ERROR_RATE_LIMIT`,
                  `NOTION_ERROR_TEMPORARILY_UNAVAILABLE`,
                  `NOTION_ERROR_PAGE_REJECTED`, `NOTION_ERROR_UNKNOWN`.
                - `HTML_REJECTED`: `{ reason: string }`, one of `too_large`,
                `css_rejected` or `invalid`.
                  Open-ended: tolerate new values.
                - `CONDITION_NOT_SUPPORTED`: `{ field: string, path: string }`,
                the condition type that is not
                  accepted and where it sits in the request. For a condition shape refused where it sits
                  also `operator: string` and, when there is an equivalent operator for `requiredConditions`,
                  `invertTo: string`.
                - `REFERENCE_NOT_FOUND`: `{ path: string, kind: string }`, where
                the unknown id sits in the
                  request and what it refers to: `document`, `product`, `tier`, `cta`, `folder`, `broadcast` or
                  `step`. Open-ended: tolerate new values.
                - `TAG_NOT_FOUND` (from a group rule): `{ tag: string }`, the
                tag name that does not exist.

                - `GROUP_REFERENCE_NOT_FOUND`: `{ groupIds: string[] }`, the
                group ids that are not in the account.

                - `GROUP_LIMIT_REACHED`: `{ limit: integer }`, the most groups
                an account can create through the API.
          description: >-
            The error. Every error response from the API has it: `code`,
            `message`, `retryable` and, for some codes, `retryAfterSeconds` and
            `details`.
  responses:
    Unauthorized:
      description: 'Missing, malformed, or revoked API key (`code: UNAUTHORIZED`).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotOnAllowlist:
      description: |
        The API is available to some accounts only, whatever the plan. If you
        expect access, check with your DocuRise contact (`code: NOT_FOUND`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: >-
        Rate limited (`code: RATE_LIMITED`, always retryable): see the
        `Retry-After` header and `X-RateLimit-*` headers. Or too many requests
        running at once (`code: TOO_MANY_CONCURRENT_REQUESTS`, always
        retryable): `Retry-After` is `1` and there are no `X-RateLimit-*`
        headers.
      headers:
        Retry-After:
          schema:
            type: integer
        X-RateLimit-Limit:
          schema:
            type: integer
        X-RateLimit-Remaining:
          schema:
            type: integer
        X-RateLimit-Reset:
          schema:
            type: integer
          description: Unix timestamp (seconds) when the limit resets.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unavailable:
      description: |
        A server-side dependency is temporarily down (`RATE_LIMIT_UNAVAILABLE`
        or `SERVICE_UNAVAILABLE`). Not a problem with the request or key;
        always retryable — honor `retryAfterSeconds` when present. The group
        endpoints (`POST /segments`, `POST /segments/preview`,
        `GET /segments/{id}`) also return it when a very heavy rule could not be
        counted within about 10 seconds: simplify the rule or retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: dr_live_<keyId>_<secret>
      description: |
        A key generated from Settings → Developers, sent as
        `Authorization: Bearer dr_live_<12 hex chars>_<64 hex chars>`. Keys
        carry explicit scopes — each endpoint states the one it requires.
        The full key is shown exactly once at generation time and cannot be
        retrieved again; only the `keyId` prefix is shown afterward. A
        revoked key fails auth on its very next request.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.