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

# Record an agreement acceptance

> Records that a person accepted one version of an agreement for a merchant. You state that they accepted, who, when and the exact wording they saw, and you are attesting to it. These details are never returned. Any agreement the merchant accepts can be recorded here, including one a create could have taken in `consent`. A `bank_debit_authorization` names the account in `bank_account`. A `nacha_acknowledgment` or a `bank_debit_authorization` needs the merchant's legal entity first. Safe to repeat: a version already on file for this merchant, for the same account where it names one, answers 200 with the existing acceptance, and nothing is recorded, even once a newer version is current or `accepted_at` would now be refused. `CONSENT_AGREEMENT_STALE` names the current version in `details`.

Credentials: `partner`, `merchant`

Permission: `agreement-acceptances:create`



## OpenAPI

````yaml /api-reference/v1/openapi.json post /merchants/{id}/agreement-acceptances
openapi: 3.1.0
info:
  title: Quidkey API
  version: 1.0.0
  description: >-
    The Quidkey public API.


    Within a version, a response can carry what this document doesn't list yet:
    a new field, a new value of an enum, a new error code. Handle a value you
    don't recognise rather than refusing the response. A client generated from
    this document turns an `enum` into a closed type unless told otherwise, so
    turn on its option for unknown values, such as openapi-generator's
    `enumUnknownDefaultCase`. A request is held to what's listed: a value it
    doesn't list is refused.
  contact:
    name: Quidkey
    url: https://docs.quidkey.com
servers:
  - url: https://api.quidkey.com/v1
security:
  - bearer: []
tags:
  - name: account_owner
  - name: agreement
  - name: agreement_acceptance
  - name: api_key
  - name: bank
  - name: bank_account
  - name: capability
  - name: country
  - name: identity_verification
  - name: legal_entity
  - name: merchant
  - name: party
  - name: payment_link
  - name: payout
  - name: transaction
  - name: webhook_endpoint
paths:
  /merchants/{id}/agreement-acceptances:
    post:
      tags:
        - agreement_acceptance
      summary: Record an agreement acceptance
      description: >-
        Records that a person accepted one version of an agreement for a
        merchant. You state that they accepted, who, when and the exact wording
        they saw, and you are attesting to it. These details are never returned.
        Any agreement the merchant accepts can be recorded here, including one a
        create could have taken in `consent`. A `bank_debit_authorization` names
        the account in `bank_account`. A `nacha_acknowledgment` or a
        `bank_debit_authorization` needs the merchant's legal entity first. Safe
        to repeat: a version already on file for this merchant, for the same
        account where it names one, answers 200 with the existing acceptance,
        and nothing is recorded, even once a newer version is current or
        `accepted_at` would now be refused. `CONSENT_AGREEMENT_STALE` names the
        current version in `details`.


        Credentials: `partner`, `merchant`


        Permission: `agreement-acceptances:create`
      operationId: agreement_acceptance.create
      parameters:
        - name: id
          in: path
          required: true
          schema:
            minLength: 1
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              additionalProperties: false
              type: object
              required:
                - agreement
                - is_accepted
                - accepted_at
                - accepted_by
                - accepted_ip
                - wording
                - locale
              properties:
                agreement:
                  $ref: '#/components/schemas/AgreementRequestLink'
                  description: >-
                    The current version of one agreement, usually from the
                    onboarding's or a capability's required actions.
                bank_account:
                  $ref: '#/components/schemas/BankAccountRequestLink'
                  description: >-
                    The merchant's `owned` account a `bank_debit_authorization`
                    authorises debits from. Required for that agreement, and
                    refused for any other.
                is_accepted:
                  const: true
                  type: boolean
                accepted_at:
                  format: date-time
                  pattern: >-
                    ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$
                  type: string
                  description: >-
                    When the person accepted. Before the agreement took effect,
                    more than 5 minutes in the future or more than 30 days old
                    is refused, with `CONSENT_ACCEPTED_AT_INVALID`.
                accepted_by:
                  additionalProperties: false
                  type: object
                  required:
                    - full_name
                    - email
                  properties:
                    full_name:
                      minLength: 1
                      maxLength: 200
                      pattern: ^[^\x00-\x1F\x7F]*$
                      description: On one line, with no control character.
                      type: string
                    email:
                      format: email
                      maxLength: 320
                      type: string
                      pattern: >-
                        ^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$
                accepted_ip:
                  anyOf:
                    - format: ipv4
                      type: string
                    - format: ipv6
                      type: string
                wording:
                  minLength: 1
                  maxLength: 10000
                  pattern: ^[^\x00-\x08\x0B\x0C\x0E-\x1F\x7F]*$
                  description: >-
                    The exact text the person saw, with no control character but
                    a line break or a tab.
                  type: string
                locale:
                  pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{1,8})*$
                  type: string
                  maxLength: 35
      responses:
        '200':
          description: >-
            The agreement_acceptance already there, in the full view: a repeat
            records nothing.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                additionalProperties: false
                type: object
                required:
                  - result
                  - entities
                  - not_included
                properties:
                  result:
                    $ref: '#/components/schemas/AgreementAcceptanceFull'
                  entities:
                    additionalProperties: false
                    description: Nothing can be included here.
                    type: object
                    properties: {}
                  not_included:
                    type: array
                    items:
                      $ref: '#/components/schemas/NotIncludedEntry'
        '201':
          description: The agreement_acceptance, in the full view.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            Location:
              description: The URL of the created resource.
              schema:
                type: string
          content:
            application/json:
              schema:
                additionalProperties: false
                type: object
                required:
                  - result
                  - entities
                  - not_included
                properties:
                  result:
                    $ref: '#/components/schemas/AgreementAcceptanceFull'
                  entities:
                    additionalProperties: false
                    description: Nothing can be included here.
                    type: object
                    properties: {}
                  not_included:
                    type: array
                    items:
                      $ref: '#/components/schemas/NotIncludedEntry'
        '400':
          description: >-
            `CONSENT_ACCEPTED_AT_INVALID`: accepted_at is before the agreement
            took effect, too far in the future or too old.


            `CONSENT_AGREEMENT_STALE`: Consent names an agreement version that
            isn't current.


            `CONSENT_NOT_ACCEPTED`: `is_accepted` must be `true`, stating that
            the person accepted.


            `UNKNOWN_AGREEMENT`: This names no agreement.


            `VALIDATION_FAILED`: The request is malformed or failed validation.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - CONSENT_ACCEPTED_AT_INVALID
            - CONSENT_AGREEMENT_STALE
            - CONSENT_NOT_ACCEPTED
            - UNKNOWN_AGREEMENT
            - VALIDATION_FAILED
        '401':
          description: '`UNAUTHENTICATED`: A valid bearer token is required.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - UNAUTHENTICATED
        '403':
          description: >-
            `FORBIDDEN`: This credential doesn't have permission for this
            endpoint.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - FORBIDDEN
        '404':
          description: '`NOT_FOUND`: Not found.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - NOT_FOUND
        '406':
          description: '`NOT_ACCEPTABLE`: This endpoint doesn''t offer the format in Accept.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - NOT_ACCEPTABLE
        '409':
          description: >-
            `LEGAL_ENTITY_REQUIRED`: The merchant needs a legal entity with a
            name first.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - LEGAL_ENTITY_REQUIRED
        '422':
          description: >-
            `AGREEMENT_NOT_ACCEPTABLE`: This agreement can't be accepted for a
            merchant.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - AGREEMENT_NOT_ACCEPTABLE
        '429':
          description: '`RATE_LIMITED`: Too many requests.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - RATE_LIMITED
        '500':
          description: '`INTERNAL_ERROR`: Something went wrong on our side.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - INTERNAL_ERROR
        '503':
          description: '`SERVICE_UNAVAILABLE`: The service is busy. Try again shortly.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - SERVICE_UNAVAILABLE
components:
  schemas:
    AgreementRequestLink:
      additionalProperties: false
      type: object
      required:
        - id
      properties:
        id:
          minLength: 1
          maxLength: 100
          type: string
        _link:
          pattern: ^/
          type: string
        _type:
          const: agreement
          type: string
      x-link-target:
        resource: agreement
        kind: request
        is_published: true
    BankAccountRequestLink:
      additionalProperties: false
      type: object
      required:
        - id
      properties:
        id:
          minLength: 1
          maxLength: 100
          type: string
        _link:
          pattern: ^/
          type: string
        _type:
          const: bank_account
          type: string
      x-link-target:
        resource: bank_account
        kind: request
        is_published: true
    AgreementAcceptanceFull:
      additionalProperties: false
      type: object
      required:
        - _type
        - _uri
        - _view
        - id
        - created_at
        - updated_at
        - merchant
        - agreement
        - bank_account
        - accepted_at
      properties:
        _type:
          const: agreement_acceptance
          type: string
        _uri:
          pattern: ^/
          description: The canonical URI, relative to the version root.
          type: string
        _view:
          const: full
          type: string
        id:
          type: string
        created_at:
          anyOf:
            - format: date-time
              pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$
              type: string
            - type: 'null'
        updated_at:
          anyOf:
            - format: date-time
              pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$
              type: string
            - type: 'null'
        merchant:
          $ref: '#/components/schemas/MerchantLink'
        agreement:
          $ref: '#/components/schemas/AgreementLink'
          description: The version accepted, which stays readable once superseded.
        bank_account:
          anyOf:
            - $ref: '#/components/schemas/BankAccountLink'
            - type: 'null'
          description: >-
            The account a `bank_debit_authorization` authorises debits from.
            `null` for any other agreement.
        accepted_at:
          format: date-time
          pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$
          type: string
          description: >-
            When the person accepted: the time the caller attested to, or, for
            an acceptance in Quidkey's own flows such as signup, when Quidkey
            recorded it.
    NotIncludedEntry:
      additionalProperties: false
      type: object
      required:
        - link
        - reason
      properties:
        link:
          $ref: '#/components/schemas/AnyLink'
        reason:
          type: string
          enum:
            - no_permission
            - not_published
          description: >-
            Why this link has no entity.


            - `no_permission`: This credential can't read it. Fetching it
            answers 403, or 404 where a 403 would reveal that it exists.

            - `not_published`: The API doesn't show it: a type it doesn't
            publish, or a record it doesn't show on a type it does, such as a
            failed payout. Fetching it, where it has a URI, answers 404.
    Error:
      additionalProperties: false
      type: object
      required:
        - error
      properties:
        error:
          additionalProperties: false
          type: object
          required:
            - code
            - message
            - details
            - retryable
            - request_id
          properties:
            code:
              description: Branch on this. New codes can appear.
              type: string
            message:
              description: For people. It can change.
              type: string
            details:
              type: array
              items:
                $ref: '#/components/schemas/ErrorDetail'
            retryable:
              description: >-
                Whether sending the same request again unchanged, after a wait,
                can succeed with nothing else changing.
              type: boolean
            request_id:
              description: Quote this to support.
              type: string
    MerchantLink:
      additionalProperties: false
      type: object
      required:
        - _link
        - _type
        - id
      properties:
        _link:
          pattern: ^/
          type: string
        _type:
          const: merchant
          type: string
        id:
          type: string
      x-link-target:
        resource: merchant
        kind: resource
        is_published: true
        views:
          - full
    AgreementLink:
      additionalProperties: false
      type: object
      required:
        - _link
        - _type
        - id
      properties:
        _link:
          pattern: ^/
          type: string
        _type:
          const: agreement
          type: string
        id:
          type: string
      x-link-target:
        resource: agreement
        kind: resource
        is_published: true
        views:
          - full
    BankAccountLink:
      additionalProperties: false
      type: object
      required:
        - _link
        - _type
        - id
      properties:
        _link:
          pattern: ^/
          type: string
        _type:
          const: bank_account
          type: string
        id:
          type: string
      x-link-target:
        resource: bank_account
        kind: resource
        is_published: true
        views:
          - full
    AnyLink:
      anyOf:
        - additionalProperties: false
          type: object
          required:
            - _link
            - _type
            - id
          properties:
            _link:
              pattern: ^/
              type: string
            _type:
              type: string
            id:
              type: string
        - additionalProperties: false
          type: object
          required:
            - _type
            - id
          properties:
            _type:
              type: string
            id:
              type: string
      x-link-target:
        resource: any
        kind: any
        is_published: true
    ErrorDetail:
      anyOf:
        - additionalProperties: false
          type: object
          required:
            - field
            - message
          properties:
            field:
              type: string
            message:
              type: string
        - additionalProperties: false
          type: object
          required:
            - required_actions
            - message
          properties:
            required_actions:
              description: The `required_actions` codes holding this back.
              type: array
              items:
                type: string
            message:
              type: string
        - additionalProperties: false
          type: object
          required:
            - available_percent
            - message
          properties:
            available_percent:
              $ref: '#/components/schemas/Percent'
            message:
              type: string
        - additionalProperties: false
          type: object
          required:
            - agreement
            - message
          properties:
            agreement:
              $ref: '#/components/schemas/AgreementLink'
            message:
              type: string
        - additionalProperties: false
          type: object
          required:
            - agreement
            - current_agreement
            - message
          properties:
            agreement:
              $ref: '#/components/schemas/AgreementLink'
            current_agreement:
              $ref: '#/components/schemas/AgreementLink'
            message:
              type: string
        - additionalProperties: false
          type: object
          required:
            - legal_entity
            - message
          properties:
            legal_entity:
              $ref: '#/components/schemas/LegalEntityLink'
            message:
              type: string
    Percent:
      pattern: ^\d+(\.\d+)?$
      description: 'A percentage as a decimal string: `"25.00"` is 25%.'
      type: string
    LegalEntityLink:
      additionalProperties: false
      type: object
      required:
        - _link
        - _type
        - id
      properties:
        _link:
          pattern: ^/
          type: string
        _type:
          const: legal_entity
          type: string
        id:
          type: string
      x-link-target:
        resource: legal_entity
        kind: resource
        is_published: true
        views:
          - full
  headers:
    RequestId:
      description: Identifies this request. Quote it to support.
      schema:
        type: string
    RetryAfter:
      description: How many seconds to wait before retrying.
      schema:
        minimum: 0
        type: integer
  securitySchemes:
    bearer:
      type: http
      scheme: bearer

````

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