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

# Create objects in batch

> Create up to 100 objects of one type in a group.

Create up to 100 new objects of a given type in one request.

Set the `objectType` path parameter to the name of the object type you want to create — `Deals`, `Projects`, `Applications`, or any other object type defined in the group. See [Custom objects](/api-reference/custom-objects/overview) to find the object types available in a group. An object type that does not exist in the group fails the whole request with a `404`, whose message lists the object types of the group.

Each record takes the same fields as [create an object](/api-reference/custom-objects/create-an-object) and is created on its own: a record that fails, for instance because of an unknown custom field, does not prevent the others from being created. See [batch requests](/api-reference/batch-requests) for the 100-record limit and how to read the response. Each object comes back in full, as in the response of [create an object](/api-reference/custom-objects/create-an-object). If the API key cannot create objects in the group, every record fails.

<Warning>
  Objects are never matched with existing ones: two records with the same name,
  or a record named like an existing object, create separate objects. A batch
  retried after a timeout or a network error creates every object again. Send an
  [`Idempotency-Key`](/api-reference/idempotency) header, so that a retry
  replays the first response instead.
</Warning>

People and companies are given by ID, and must already be in the group: an unknown one, or one not in the group, is ignored. To link people or companies you are importing, create them first with [create people in batch](/api-reference/people/create-people-in-batch) or [create companies in batch](/api-reference/companies/create-companies-in-batch), and use the IDs they return.

The objects of a request are created together with their people and companies: if that fails, every record fails and no object is created. A record that succeeded but whose custom field values could not all be set carries a `warnings` list explaining what was not applied.


## OpenAPI

````yaml post /v1/groups/{groupId}/{objectType}/batch/create
openapi: 3.1.0
info:
  title: Folk External API
  description: >-
    Folk's public REST API lets you manage workspaces, groups, contacts, and
    real-time triggers.
  version: '2025-06-09'
  contact:
    name: folk
    email: tech@folk.app
    url: https://folk.app
servers:
  - url: https://api.folk.app
    description: Folk's public API production base URL.
    x-internal: false
security: []
tags:
  - name: Companies
    description: Operations related to companies.
  - name: Credits
    description: Operations related to credits.
  - name: Deals
    description: Operations related to deals.
  - name: Groups
    description: Operations related to groups.
  - name: Group members
    description: Operations related to group members.
  - name: Group custom fields
    description: Operations related to group custom fields.
  - name: Interactions
    description: Operations related to interactions.
  - name: Notes
    description: Operations related to notes.
  - name: People
    description: Operations related to people.
  - name: Reminders
    description: Operations related to reminders.
  - name: Tasks
    description: Operations related to tasks.
  - name: Users
    description: Operations related to users.
  - name: Webhooks
    description: Operations related to webhooks.
paths:
  /v1/groups/{groupId}/{objectType}/batch/create:
    post:
      tags:
        - Deals
      summary: Create deals in batch
      description: >-
        Create up to 100 new deals of one type in a group, each with the fields
        `POST /v1/groups/{groupId}/{objectType}` accepts. Each record is created
        on its own: one that fails does not prevent the others from being
        created.


        **Records are never matched with existing deals.** Two records with the
        same name, or a record naming an existing deal, create separate deals. A
        batch retried after a timeout or a network error therefore creates every
        deal a second time: send an `Idempotency-Key` header, so that a retry
        replays the first response instead.


        **People and companies are given by ID**, and must already be in the
        group: an unknown one, or one not in the group, is ignored, as in `POST
        /v1/groups/{groupId}/{objectType}`. To link people or companies you are
        importing, create them first, with [Create people in
        batch](/api-reference/people/create-people-in-batch) or [Create
        companies in batch](/api-reference/companies/create-companies-in-batch),
        and use the IDs they return.


        The deals of a request are created together with their people and
        companies: if that fails, every record fails and no deal is created.


        An object type that does not exist in the group fails the whole request
        with a `404`, whose message lists the object types of the group.
      operationId: batchCreateDeals
      parameters:
        - schema:
            type: string
            minLength: 40
            maxLength: 40
          required: true
          description: >-
            The ID of the group the deals belong to. Can be retrieved from the
            [List groups](/api-reference/groups/list-groups) endpoint.
          example: grp_bc984b3f-0386-434d-82d7-a91eb6badd71
          name: groupId
          in: path
        - schema:
            type: string
            maxLength: 500
          required: true
          description: >-
            The name of a deal custom field that can be retrieved from the [List
            group custom
            fields](/api-reference/group-custom-fields/list-group-custom-fields)
            endpoint.
          example: Deals
          name: objectType
          in: path
        - schema:
            type: string
            maxLength: 255
            description: >-
              A unique key, such as a UUID, that makes retrying this request
              safe: a retry with the same key and body returns the original
              response without running the operation again. Keys are kept for 24
              hours after the request completes.
            example: 8e03978e-40d5-43e8-bc93-6894a57f9324
          required: false
          name: Idempotency-Key
          in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                records:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        maxLength: 1000
                        description: The name of the deal.
                        example: Project Alpha
                      companies:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              minLength: 40
                              maxLength: 40
                          required:
                            - id
                          additionalProperties: false
                        maxItems: 20
                        description: The companies associated with the deal.
                        example:
                          - id: com_92346499-30bf-4278-ae8e-4aa3ae2ace2c
                      people:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              minLength: 40
                              maxLength: 40
                          required:
                            - id
                          additionalProperties: false
                        maxItems: 20
                        description: The people associated with the deal.
                        example:
                          - id: per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2
                      customFieldValues:
                        type: object
                        additionalProperties:
                          anyOf:
                            - type: 'null'
                            - type: string
                              maxLength: 5000
                            - type: number
                              minimum: -1.7976931348623157e+308
                              maximum: 1.7976931348623157e+308
                            - type: array
                              items:
                                anyOf:
                                  - type: string
                                    maxLength: 500
                                  - type: object
                                    properties:
                                      id:
                                        type: string
                                        minLength: 40
                                        maxLength: 40
                                    required:
                                      - id
                                  - type: object
                                    properties:
                                      email:
                                        type: string
                                        maxLength: 254
                                    required:
                                      - email
                              maxItems: 1000
                            - type: 'null'
                        description: >-
                          The custom field values associated with the deal. The
                          format is the following:

                          ```json

                          {
                            "<customFieldName>": "<customFieldValue>"
                          }

                          ```


                          The format of the custom field value depends on the
                          type of the custom field:


                          - `textField`: string, eg: `"Foo"`

                          - `numericField`: number or numeric string, eg: `42`
                          or `"42"`

                          - `dateField`: ISO 8601 string (YYYY-MM-DD), eg:
                          `"2021-01-01"`

                          - `singleSelect`: string (option label), eg:
                          `"Active"`

                          - `multipleSelect`: array of strings (option labels),
                          eg: `["B2B", "B2C"]`

                          - `userField`: array of objects with either `id`
                          (workspace user id) or `email` (workspace user email)
                          property, eg: `[{"id":
                          "usr_a23373bb-5296-4c59-b2e8-8f121707d562"}, {"email":
                          "jane@example.com"}]`


                          Passing a `null` value or an empty array will unset
                          the custom field value.
                        properties: {}
                        example:
                          Status: Active
                          Deal value: '42000'
                          Close date: '2021-01-01'
                          Assignee:
                            - id: usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6
                            - email: jane@example.com
                    additionalProperties: false
                    example:
                      name: Project Alpha
                      companies:
                        - id: com_92346499-30bf-4278-ae8e-4aa3ae2ace2c
                      people:
                        - id: per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2
                      customFieldValues:
                        Status: Active
                  maxItems: 100
              required:
                - records
              example:
                records:
                  - name: Project Alpha
                    companies:
                      - id: com_92346499-30bf-4278-ae8e-4aa3ae2ace2c
                    people:
                      - id: per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2
                    customFieldValues:
                      Status: Active
      responses:
        '200':
          description: The outcome of each record, with each created deal.
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            X-RateLimit-Limit-Burst:
              $ref: '#/components/headers/X-RateLimit-Limit-Burst'
            X-RateLimit-Remaining-Burst:
              $ref: '#/components/headers/X-RateLimit-Remaining-Burst'
            X-RateLimit-Reset-Burst:
              $ref: '#/components/headers/X-RateLimit-Reset-Burst'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      results:
                        type: array
                        items:
                          oneOf:
                            - type: object
                              properties:
                                status:
                                  type: string
                                  enum:
                                    - succeeded
                                data:
                                  $ref: '#/components/schemas/Deal'
                                warnings:
                                  type: array
                                  items:
                                    type: string
                                  description: >-
                                    What could not be applied to this record
                                    although it succeeded, such as a group it
                                    could not be added to.
                              required:
                                - status
                                - data
                            - type: object
                              properties:
                                status:
                                  type: string
                                  enum:
                                    - failed
                                error:
                                  $ref: '#/components/schemas/BatchRecordError'
                              required:
                                - status
                                - error
                        description: >-
                          One result per record, in the order of `records`: the
                          first result is the outcome of the first record.
                    required:
                      - results
                    example:
                      results:
                        - status: succeeded
                          data:
                            id: obj_183ed5cc-3182-45de-84d1-d520f2604810
                            name: Project Alpha
                            companies:
                              - id: com_92346499-30bf-4278-ae8e-4aa3ae2ace2c
                                name: Tech Corp
                            people:
                              - id: per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2
                                fullName: John Doe
                            createdAt: '2021-01-01T00:00:00.000Z'
                            createdBy:
                              id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71
                              fullName: John Doe
                              email: john.doe@example.com
                            customFieldValues:
                              Status: Active
                              Deal value: '42000'
                              Close date: '2021-01-01'
                              Assignee:
                                - id: usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6
                                  fullName: Jane Doe
                                  email: jane@example.com
                        - status: failed
                          error:
                            code: NOT_FOUND
                            message: Not found.
                            documentationUrl: >-
                              https://developer.folk.app/api-reference/errors#not-found
                  deprecations:
                    type: array
                    items:
                      type: string
                    example:
                      - This field is deprecated
                required:
                  - data
              example:
                data:
                  results:
                    - status: succeeded
                      data:
                        id: obj_183ed5cc-3182-45de-84d1-d520f2604810
                        name: Project Alpha
                        companies:
                          - id: com_92346499-30bf-4278-ae8e-4aa3ae2ace2c
                            name: Tech Corp
                        people:
                          - id: per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2
                            fullName: John Doe
                        createdAt: '2021-01-01T00:00:00.000Z'
                        createdBy:
                          id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71
                          fullName: John Doe
                          email: john.doe@example.com
                        customFieldValues:
                          Status: Active
                          Deal value: '42000'
                          Close date: '2021-01-01'
                          Assignee:
                            - id: usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6
                              fullName: Jane Doe
                              email: jane@example.com
                    - status: failed
                      error:
                        code: NOT_FOUND
                        message: Not found.
                        documentationUrl: >-
                          https://developer.folk.app/api-reference/errors#not-found
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
        - bearerApiKeyAuth: []
components:
  headers:
    X-RateLimit-Limit:
      schema:
        type: integer
        example: 1000
      description: >-
        The maximum number of requests that you can make in the current rate
        limit window.
    X-RateLimit-Remaining:
      schema:
        type: integer
        example: 998
      description: The number of requests remaining in the current rate limit window.
    X-RateLimit-Reset:
      schema:
        type: integer
        example: 1747322958
      description: >-
        The time at which the current rate limit window resets, in UTC epoch
        seconds.
    X-RateLimit-Limit-Burst:
      schema:
        type: integer
        example: 20
      description: >-
        The maximum number of requests that you can make in the current burst
        rate limit window.
    X-RateLimit-Remaining-Burst:
      schema:
        type: integer
        example: 18
      description: The number of requests remaining in the current burst rate limit window.
    X-RateLimit-Reset-Burst:
      schema:
        type: integer
        example: 1747322902
      description: >-
        The time at which the current burst rate limit window resets, in UTC
        epoch seconds.
    RateLimit-Policy:
      schema:
        type: string
        example: '"default";q=600;w=60, "burst";q=20;w=2'
      description: >-
        The rate limit policies applied to the request, as defined by the IETF
        RateLimit header fields draft. `q` is the number of requests allowed per
        window and `w` the window length in seconds.
    RateLimit:
      schema:
        type: string
        example: '"default";r=598;t=42, "burst";r=18;t=1'
      description: >-
        The current usage of each rate limit policy, as defined by the IETF
        RateLimit header fields draft. `r` is the number of requests remaining
        and `t` the number of seconds until the window resets.
    Retry-After:
      schema:
        type: integer
        example: 60
      description: >-
        The number of seconds to wait before making a new request after hitting
        the rate limit.
  schemas:
    Deal:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
          description: The name of the deal.
          example: Project Alpha
        companies:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
                description: The name of the company.
                example: Tech Corp
            required:
              - id
              - name
        people:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              fullName:
                type: string
                description: The name of the person.
                example: John Doe
            required:
              - id
              - fullName
        createdAt:
          type:
            - string
            - 'null'
          minLength: 20
          maxLength: 40
          description: The date and time the deal was created, in ISO format.
          example: '2021-01-01T00:00:00.000Z'
        createdBy:
          $ref: '#/components/schemas/User'
        customFieldValues:
          type: object
          additionalProperties:
            anyOf:
              - type: 'null'
              - type: string
                description: A custom field value as a string.
                example: Value 1
              - type: array
                items:
                  type: string
                description: An array of values for the custom field.
                example:
                  - Value 1
                  - Value 2
              - type: array
                items:
                  $ref: '#/components/schemas/User'
                description: An array of users associated with the custom field.
                example:
                  - id: usr_44b85098-441b-4d7f-9d72-c079b1caec45
                    fullName: Jane Doe
                    email: jane@example.com
                  - id: usr_a95a1b90-8e88-4855-bc29-d47b8e2704e1
                    fullName: John Doe
                    email: john@example.com
              - type: array
                items:
                  anyOf:
                    - type: object
                      properties:
                        id:
                          type: string
                        fullName:
                          type: string
                        entityType:
                          type: string
                          enum:
                            - person
                      required:
                        - id
                        - fullName
                        - entityType
                    - type: object
                      properties:
                        id:
                          type: string
                        fullName:
                          type: string
                        entityType:
                          type: string
                          enum:
                            - company
                      required:
                        - id
                        - fullName
                        - entityType
                    - type: object
                      properties:
                        id:
                          type: string
                        fullName:
                          type: string
                        entityType:
                          type: string
                          enum:
                            - object
                      required:
                        - id
                        - fullName
                        - entityType
                description: An array of relationships associated with the custom field.
                example:
                  - id: per_183ed5cc-3182-45de-84d1-d520f2604810
                    fullName: John Doe
                    entityType: person
                  - id: com_92346499-30bf-4278-ae8e-4aa3ae2ace2c
                    fullName: Tech Corp
                    entityType: company
              - type: 'null'
      required:
        - id
        - name
        - companies
        - people
        - createdAt
        - createdBy
        - customFieldValues
      description: A deal in the workspace.
      example:
        id: obj_183ed5cc-3182-45de-84d1-d520f2604810
        name: Project Alpha
        companies:
          - id: com_92346499-30bf-4278-ae8e-4aa3ae2ace2c
            name: Tech Corp
        people:
          - id: per_5fa60242-0756-4e31-8cca-30c2c5ff1ac2
            fullName: John Doe
        createdAt: '2021-01-01T00:00:00.000Z'
        createdBy:
          id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71
          fullName: John Doe
          email: john.doe@example.com
        customFieldValues:
          Status: Active
          Deal value: '42000'
          Close date: '2021-01-01'
          Assignee:
            - id: usr_c3606e3b-0a92-4849-90e5-88a8d3f388d6
              fullName: Jane Doe
              email: jane@example.com
    BatchRecordError:
      type: object
      properties:
        code:
          type: string
          example: NOT_FOUND
        message:
          type: string
          example: Not found.
        documentationUrl:
          type: string
          format: uri
          example: https://developer.folk.app/api-reference/errors#not-found
        details:
          type: object
          additionalProperties: true
      required:
        - code
        - message
        - documentationUrl
      description: Why this record did not succeed.
      example:
        code: NOT_FOUND
        message: Not found.
        documentationUrl: https://developer.folk.app/api-reference/errors#not-found
    User:
      type: object
      properties:
        id:
          type: string
        fullName:
          type: string
        email:
          type: string
      required:
        - id
        - fullName
        - email
      description: A user in the workspace.
      example:
        id: usr_bc984b3f-0386-434d-82d7-a91eb6badd71
        fullName: John Doe
        email: john.doe@example.com
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: TOO_MANY_REQUESTS
            message:
              type: string
              example: You have exceeded your rate limit.
            documentationUrl:
              type: string
              format: uri
              example: https://developer.folk.app/api-reference/errors#rate-limiting
            requestId:
              type: string
              format: uuid
              example: 123e4567-e89b-12d3-a456-426614174000
            timestamp:
              type: string
              format: date-time
              example: '2025-10-01T12:00:00Z'
            details:
              type: object
              additionalProperties: true
              example:
                policy: burst
                limit: 20
                remaining: 0
                windowSeconds: 2
                retryAfter: '2025-10-01T12:00:02.000Z'
          required:
            - code
            - message
            - documentationUrl
            - requestId
            - timestamp
      required:
        - error
      description: Error response containing error details.
    RateLimitError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: TOO_MANY_REQUESTS
            message:
              type: string
              example: You have exceeded your rate limit.
            documentationUrl:
              type: string
              format: uri
              example: https://developer.folk.app/api-reference/errors#rate-limiting
            requestId:
              type: string
              format: uuid
              example: 123e4567-e89b-12d3-a456-426614174000
            timestamp:
              type: string
              format: date-time
              example: '2025-10-01T12:00:00Z'
            details:
              type: object
              properties:
                policy:
                  type: string
                  enum:
                    - default
                    - burst
                  description: The name of the rate limit policy.
                limit:
                  type: integer
                  description: The maximum number of requests allowed per window.
                remaining:
                  type: integer
                  description: The number of requests remaining in the current window.
                windowSeconds:
                  type: integer
                  description: The length of the window, in seconds.
                retryAfter:
                  type: string
                  format: date-time
                  description: When the current window resets.
                policies:
                  type: array
                  items:
                    type: object
                    properties:
                      policy:
                        type: string
                        enum:
                          - default
                          - burst
                        description: The name of the rate limit policy.
                      limit:
                        type: integer
                        description: The maximum number of requests allowed per window.
                      remaining:
                        type: integer
                        description: >-
                          The number of requests remaining in the current
                          window.
                      windowSeconds:
                        type: integer
                        description: The length of the window, in seconds.
                      retryAfter:
                        type: string
                        format: date-time
                        description: When the current window resets.
                    required:
                      - policy
                      - limit
                      - remaining
                      - windowSeconds
                      - retryAfter
                  description: >-
                    The status of every rate limit policy applied to the
                    request.
              required:
                - policy
                - limit
                - remaining
                - windowSeconds
                - retryAfter
                - policies
              description: >-
                The exceeded rate limit policy. When several are exceeded, the
                one resetting last.
          required:
            - code
            - message
            - documentationUrl
            - requestId
            - timestamp
            - details
      required:
        - error
      description: Error response returned when a rate limit is exceeded.
  responses:
    BadRequest:
      description: The request was unacceptable, often due to missing an invalid parameter.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-RateLimit-Limit-Burst:
          $ref: '#/components/headers/X-RateLimit-Limit-Burst'
        X-RateLimit-Remaining-Burst:
          $ref: '#/components/headers/X-RateLimit-Remaining-Burst'
        X-RateLimit-Reset-Burst:
          $ref: '#/components/headers/X-RateLimit-Reset-Burst'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INVALID_REQUEST
              message: The request was invalid.
              documentationUrl: https://developer.folk.app/api-reference/errors#bad-request
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    Unauthorized:
      description: No valid API key provided.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-RateLimit-Limit-Burst:
          $ref: '#/components/headers/X-RateLimit-Limit-Burst'
        X-RateLimit-Remaining-Burst:
          $ref: '#/components/headers/X-RateLimit-Remaining-Burst'
        X-RateLimit-Reset-Burst:
          $ref: '#/components/headers/X-RateLimit-Reset-Burst'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHORIZED
              message: No valid API key provided.
              documentationUrl: https://developer.folk.app/api-reference/errors#unauthorized
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    Forbidden:
      description: The API key doesn’t have permissions to perform the request.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-RateLimit-Limit-Burst:
          $ref: '#/components/headers/X-RateLimit-Limit-Burst'
        X-RateLimit-Remaining-Burst:
          $ref: '#/components/headers/X-RateLimit-Remaining-Burst'
        X-RateLimit-Reset-Burst:
          $ref: '#/components/headers/X-RateLimit-Reset-Burst'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: FORBIDDEN
              message: The API key doesn’t have permissions to perform the request.
              documentationUrl: https://developer.folk.app/api-reference/errors#forbidden
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    NotFound:
      description: The requested resource doesn’t exist.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-RateLimit-Limit-Burst:
          $ref: '#/components/headers/X-RateLimit-Limit-Burst'
        X-RateLimit-Remaining-Burst:
          $ref: '#/components/headers/X-RateLimit-Remaining-Burst'
        X-RateLimit-Reset-Burst:
          $ref: '#/components/headers/X-RateLimit-Reset-Burst'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: RESOURCE_NOT_FOUND
              message: The requested resource was not found.
              documentationUrl: https://developer.folk.app/api-reference/errors#not-found
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    Conflict:
      description: A request with the same `Idempotency-Key` is still being processed.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-RateLimit-Limit-Burst:
          $ref: '#/components/headers/X-RateLimit-Limit-Burst'
        X-RateLimit-Remaining-Burst:
          $ref: '#/components/headers/X-RateLimit-Remaining-Burst'
        X-RateLimit-Reset-Burst:
          $ref: '#/components/headers/X-RateLimit-Reset-Burst'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: IDEMPOTENCY_REQUEST_IN_PROGRESS
              message: >-
                A request with the same Idempotency-Key is still being
                processed. Retry once it has completed.
              documentationUrl: https://developer.folk.app/api-reference/idempotency#errors
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    UnprocessableEntity:
      description: >-
        The request was unacceptable, often due to missing or invalid
        parameters.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-RateLimit-Limit-Burst:
          $ref: '#/components/headers/X-RateLimit-Limit-Burst'
        X-RateLimit-Remaining-Burst:
          $ref: '#/components/headers/X-RateLimit-Remaining-Burst'
        X-RateLimit-Reset-Burst:
          $ref: '#/components/headers/X-RateLimit-Reset-Burst'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNPROCESSABLE_ENTITY
              message: Invalid query parameters
              documentationUrl: >-
                https://developer.folk.app/api-reference/errors#unprocessable-entity
              details:
                issues:
                  - code: too_small
                    minimum: 1
                    type: number
                    inclusive: true
                    exact: false
                    message: Number must be greater than or equal to 1
                    path:
                      - limit
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    TooManyRequests:
      description: >-
        Too many requests hit the API too quickly. We recommend an exponential
        backoff of your requests.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-RateLimit-Limit-Burst:
          $ref: '#/components/headers/X-RateLimit-Limit-Burst'
        X-RateLimit-Remaining-Burst:
          $ref: '#/components/headers/X-RateLimit-Remaining-Burst'
        X-RateLimit-Reset-Burst:
          $ref: '#/components/headers/X-RateLimit-Reset-Burst'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitError'
          example:
            error:
              code: TOO_MANY_REQUESTS
              message: You have exceeded your rate limit.
              documentationUrl: https://developer.folk.app/api-reference/errors#rate-limiting
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
              details:
                policy: burst
                limit: 20
                remaining: 0
                windowSeconds: 2
                retryAfter: '2025-10-01T12:00:02.000Z'
                policies:
                  - policy: default
                    limit: 600
                    remaining: 412
                    windowSeconds: 60
                    retryAfter: '2025-10-01T12:01:00.000Z'
                  - policy: burst
                    limit: 20
                    remaining: 0
                    windowSeconds: 2
                    retryAfter: '2025-10-01T12:00:02.000Z'
    InternalServerError:
      description: Something went wrong on our end.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INTERNAL_SERVER_ERROR
              message: An internal server error occurred.
              documentationUrl: >-
                https://developer.folk.app/api-reference/errors#internal-server-error
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
    ServiceUnavailable:
      description: The server is overloaded or down for maintenance.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: SERVICE_UNAVAILABLE
              message: The service is currently unavailable.
              documentationUrl: >-
                https://developer.folk.app/api-reference/errors#service-unavailable
              requestId: 123e4567-e89b-12d3-a456-426614174000
              timestamp: '2025-10-01T12:00:00Z'
  securitySchemes:
    bearerApiKeyAuth:
      type: http
      scheme: bearer
      description: API key for authentication

````

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