acknowledgement

Last updated Jun 14, 2026

TL;DR

422 acknowledgement_required fires when a binding mutation is missing one or more Acknowledgement records that the operation declares via x-matter-required-acknowledgements. Recover by fetching canonical text from GET /v1/acknowledgements, presenting each missing slug to the natural-person stakeholder, capturing affirmative acceptance, and retrying the mutation with acknowledgements[] populated. Use a fresh Idempotency-Key on retry — the body changed.

After reading this page you'll know the exact 422 response shape, when the error fires, and the canonical recovery flow with cURL on both sides.

When it fires

Matter returns 422 acknowledgement_required when:

A binding mutation declares required acknowledgements via x-matter-required-acknowledgements on the operation, and
The request body's acknowledgements[] does not contain a valid, unexpired record for one or more required slugs, and
The token does not carry a matching standing acknowledgement that satisfies the requirement (for example, incorporator_signature_authorized on the token can satisfy the per-action formation_is_legally_binding requirement on POST /v1/entities/{id}/submit).

The error stops the mutation before any state is touched. No artifact is created, no webhook fires, no idempotency record is written.

Response shape

{
  "type": "https://mattermode.com/docs/errors/acknowledgement_required",
  "title": "Acknowledgement required",
  "status": 422,
  "detail": "This action requires acknowledgements that are missing or expired.",
  "code": "acknowledgement_required",
  "request_id": "req_Qw9xYz8A",
  "doc_url": "https://mattermode.com/docs/api/conventions/errors/acknowledgement-required",
  "required": [
    "formation_is_legally_binding",
    "formation_creates_tax_obligations"
  ],
  "text_url": "https://mattermode.com/legal/acks/?slugs=formation_is_legally_binding,formation_creates_tax_obligations",
  "disclosure_packet_url": "https://api.mattermode.com/v1/entities/ent_Nq3KcAbc/submit?dry_run=true"
}

Field	Type	Notes
`type`	string	RFC 7807 type URI for this error.
`title`	string	Short human-readable title.
`status`	integer	Always `422`.
`detail`	string	Localised prose. Do not match on this — it is subject to change.
`code`	string	Always `acknowledgement_required`. The stable handle.
`request_id`	string	Trace ID — log this on every error.
`doc_url`	string	Link to this page.
`required`	`AcknowledgementSlug[]`	The slugs that are missing or expired.
`text_url`	string	Server-rendered HTML with canonical text for every slug in `required[]`. Suitable for embedding in a signing UI.
`disclosure_packet_url`	string	Dry-run URL for the same mutation. Returns the full `DisclosurePacket` with consequences and `who_bears_risk: "customer"`.

Triggering the error

A POST /v1/entities/{id}/submit call without acknowledgements:

curl -X POST https://api.mattermode.com/v1/entities/ent_Nq3KcAbc/submit \
  -H "Authorization: Bearer $MATTER_KEY" \
  -H "Matter-Version: 2026-05-01" \
  -H "Idempotency-Key: 7a0c3b8e-4f52-4d91-b7f2-c0b0b4a3d1e9" \
  -d '{}'

Response:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json
Matter-Request-Id: req_Qw9xYz8A

{
  "type": "https://mattermode.com/docs/errors/acknowledgement_required",
  "title": "Acknowledgement required",
  "status": 422,
  "detail": "This action requires acknowledgements that are missing or expired.",
  "code": "acknowledgement_required",
  "request_id": "req_Qw9xYz8A",
  "doc_url": "https://mattermode.com/docs/api/conventions/errors/acknowledgement-required",
  "required": [
    "formation_is_legally_binding",
    "formation_creates_tax_obligations",
    "not_legal_advice",
    "not_tax_advice"
  ],
  "text_url": "https://mattermode.com/legal/acks/?slugs=formation_is_legally_binding,formation_creates_tax_obligations,not_legal_advice,not_tax_advice",
  "disclosure_packet_url": "https://api.mattermode.com/v1/entities/ent_Nq3KcAbc/submit?dry_run=true"
}

Recovery

The recovery is a four-step flow.

Fetch canonical text for the missing slugs. Use GET /v1/acknowledgements?slug=… for each slug, or load the server-rendered HTML at text_url for inline display. Always use canonical text — never hardcode acknowledgement language client-side.

Present each acknowledgement to the natural-person stakeholder. The stakeholder must be a Stakeholder on the target entity (or, for token-creation acks, the account holder). Render the canonical text, require an affirmative click on each slug, and capture the accepted_at, ip, and user_agent at the moment of click.

(Optional, recommended) Read the DisclosurePacket. Fetch disclosure_packet_url to surface the plain-English consequences, irreversible effects, and ongoing obligations to the stakeholder before they sign. See disclaimers.

Retry the mutation with acknowledgements[] populated and a fresh Idempotency-Key. The original key is now bound to a different request body — reusing it returns 409 idempotency_key_reused_with_different_body. Mint a new UUID.

Fetching canonical text

curl https://api.mattermode.com/v1/acknowledgements?slug=formation_is_legally_binding \
  -H "Authorization: Bearer $MATTER_KEY" \
  -H "Matter-Version: 2026-05-01"

{
  "object": "list",
  "data": [
    {
      "slug": "formation_is_legally_binding",
      "current_version": "2026-04-01",
      "title": "Formation is legally binding",
      "text": "By submitting this formation, I, the named incorporator stakeholder, understand and agree that the entity will exist as a legal person under the laws of the jurisdiction of formation immediately upon acceptance of the certificate by the secretary of state. I understand this action cannot be undone by simply cancelling the request after submission.",
      "text_url": "https://mattermode.com/legal/acks/formation_is_legally_binding/2026-04-01",
      "audience": "natural_person",
      "expires_after_days": 90,
      "supersedes": ["2025-09-01"]
    }
  ],
  "has_more": false,
  "url": "/v1/acknowledgements"
}

Resolved retry

curl -X POST https://api.mattermode.com/v1/entities/ent_Nq3KcAbc/submit \
  -H "Authorization: Bearer $MATTER_KEY" \
  -H "Matter-Version: 2026-05-01" \
  -H "Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef0123456789" \
  -d '{
    "acknowledgements": [
      {
        "slug": "formation_is_legally_binding",
        "version": "2026-04-01",
        "accepted_by_stakeholder_id": "stk_7Hpx9WxY",
        "accepted_at": 1745539200,
        "ip": "203.0.113.42",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4)"
      },
      {
        "slug": "formation_creates_tax_obligations",
        "version": "2026-04-01",
        "accepted_by_stakeholder_id": "stk_7Hpx9WxY",
        "accepted_at": 1745539200,
        "ip": "203.0.113.42",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4)"
      },
      {
        "slug": "not_legal_advice",
        "version": "2026-01-01",
        "accepted_by_stakeholder_id": "stk_7Hpx9WxY",
        "accepted_at": 1745539200,
        "ip": "203.0.113.42",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4)"
      },
      {
        "slug": "not_tax_advice",
        "version": "2026-01-01",
        "accepted_by_stakeholder_id": "stk_7Hpx9WxY",
        "accepted_at": 1745539200,
        "ip": "203.0.113.42",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4)"
      }
    ]
  }'

Response:

HTTP/1.1 202 Accepted
Content-Type: application/json
Matter-Request-Id: req_Bb2cDd3E

{
  "id": "ent_Nq3KcAbc",
  "object": "entity",
  "state": "submitted",
  "submitted_at": 1745539200,
  "filing_id": "flg_2x7Vc3Mn",
  "disclaimer": {
    "version": "2026-01-01",
    "text": "Matter is a software platform, not a law firm. Matter does not provide legal, tax, or securities advice. The customer is solely responsible for the legal and tax consequences of this action and should consult qualified professionals before proceeding.",
    "text_url": "https://mattermode.com/legal/disclaimer/2026-01-01"
  }
}

The terminal outcome (entity.registered or entity.rejected) arrives via webhook. See the lifecycle reference.

Common mistakes

Mistake	What happens	Fix
Reusing the original `Idempotency-Key` on retry	`409 idempotency_key_reused_with_different_body` — the body changed when you added `acknowledgements[]`.	Mint a new UUID for the retry.
Setting `accepted_by_stakeholder_id` to an `agt_…` identity	`422 invalid_request` — agents are not natural persons and cannot acknowledge.	Set it to a `stk_…` ID for a Stakeholder on the entity.
Hardcoding ack text client-side	Silent drift when slugs are versioned.	Always pull canonical text from `GET /v1/acknowledgements`.
Using a stale acknowledgement (older than 90 days)	`422 acknowledgement_required` returns again with the same slugs in `required[]`.	Re-present the ack to the stakeholder and capture a fresh `accepted_at`.
Setting `accepted_at` in the future or far in the past	`422 invalid_request` — `accepted_at` must be within 5 minutes of server time.	Use the actual moment of affirmative click. Do not pre-fill from a saved draft.

Acknowledgements — the full slug catalog, request shape, expiry, and standing acceptance semantics.
Legal basis — how acknowledgements satisfy UETA §14 on Rail 2 agent signatures.
Disclaimers — the DisclosurePacket returned by disclosure_packet_url.
Errors — the common RFC 7807 envelope and the full error catalog.
Idempotency — why you need a fresh Idempotency-Key on retry.

Last updated Jun 14, 2026

TL;DR

After reading this page you'll know the exact 422 response shape, when the error fires, and the canonical recovery flow with cURL on both sides.

When it fires

Matter returns 422 acknowledgement_required when:

A binding mutation declares required acknowledgements via x-matter-required-acknowledgements on the operation, and
The request body's acknowledgements[] does not contain a valid, unexpired record for one or more required slugs, and
The token does not carry a matching standing acknowledgement that satisfies the requirement (for example, incorporator_signature_authorized on the token can satisfy the per-action formation_is_legally_binding requirement on POST /v1/entities/{id}/submit).

The error stops the mutation before any state is touched. No artifact is created, no webhook fires, no idempotency record is written.

Response shape

{
  "type": "https://mattermode.com/docs/errors/acknowledgement_required",
  "title": "Acknowledgement required",
  "status": 422,
  "detail": "This action requires acknowledgements that are missing or expired.",
  "code": "acknowledgement_required",
  "request_id": "req_Qw9xYz8A",
  "doc_url": "https://mattermode.com/docs/api/conventions/errors/acknowledgement-required",
  "required": [
    "formation_is_legally_binding",
    "formation_creates_tax_obligations"
  ],
  "text_url": "https://mattermode.com/legal/acks/?slugs=formation_is_legally_binding,formation_creates_tax_obligations",
  "disclosure_packet_url": "https://api.mattermode.com/v1/entities/ent_Nq3KcAbc/submit?dry_run=true"
}

Field	Type	Notes
`type`	string	RFC 7807 type URI for this error.
`title`	string	Short human-readable title.
`status`	integer	Always `422`.
`detail`	string	Localised prose. Do not match on this — it is subject to change.
`code`	string	Always `acknowledgement_required`. The stable handle.
`request_id`	string	Trace ID — log this on every error.
`doc_url`	string	Link to this page.
`required`	`AcknowledgementSlug[]`	The slugs that are missing or expired.
`text_url`	string	Server-rendered HTML with canonical text for every slug in `required[]`. Suitable for embedding in a signing UI.
`disclosure_packet_url`	string	Dry-run URL for the same mutation. Returns the full `DisclosurePacket` with consequences and `who_bears_risk: "customer"`.

Triggering the error

A POST /v1/entities/{id}/submit call without acknowledgements:

curl -X POST https://api.mattermode.com/v1/entities/ent_Nq3KcAbc/submit \
  -H "Authorization: Bearer $MATTER_KEY" \
  -H "Matter-Version: 2026-05-01" \
  -H "Idempotency-Key: 7a0c3b8e-4f52-4d91-b7f2-c0b0b4a3d1e9" \
  -d '{}'

Response:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json
Matter-Request-Id: req_Qw9xYz8A

{
  "type": "https://mattermode.com/docs/errors/acknowledgement_required",
  "title": "Acknowledgement required",
  "status": 422,
  "detail": "This action requires acknowledgements that are missing or expired.",
  "code": "acknowledgement_required",
  "request_id": "req_Qw9xYz8A",
  "doc_url": "https://mattermode.com/docs/api/conventions/errors/acknowledgement-required",
  "required": [
    "formation_is_legally_binding",
    "formation_creates_tax_obligations",
    "not_legal_advice",
    "not_tax_advice"
  ],
  "text_url": "https://mattermode.com/legal/acks/?slugs=formation_is_legally_binding,formation_creates_tax_obligations,not_legal_advice,not_tax_advice",
  "disclosure_packet_url": "https://api.mattermode.com/v1/entities/ent_Nq3KcAbc/submit?dry_run=true"
}

Recovery

The recovery is a four-step flow.

Fetching canonical text

curl https://api.mattermode.com/v1/acknowledgements?slug=formation_is_legally_binding \
  -H "Authorization: Bearer $MATTER_KEY" \
  -H "Matter-Version: 2026-05-01"

{
  "object": "list",
  "data": [
    {
      "slug": "formation_is_legally_binding",
      "current_version": "2026-04-01",
      "title": "Formation is legally binding",
      "text": "By submitting this formation, I, the named incorporator stakeholder, understand and agree that the entity will exist as a legal person under the laws of the jurisdiction of formation immediately upon acceptance of the certificate by the secretary of state. I understand this action cannot be undone by simply cancelling the request after submission.",
      "text_url": "https://mattermode.com/legal/acks/formation_is_legally_binding/2026-04-01",
      "audience": "natural_person",
      "expires_after_days": 90,
      "supersedes": ["2025-09-01"]
    }
  ],
  "has_more": false,
  "url": "/v1/acknowledgements"
}

Resolved retry

curl -X POST https://api.mattermode.com/v1/entities/ent_Nq3KcAbc/submit \
  -H "Authorization: Bearer $MATTER_KEY" \
  -H "Matter-Version: 2026-05-01" \
  -H "Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef0123456789" \
  -d '{
    "acknowledgements": [
      {
        "slug": "formation_is_legally_binding",
        "version": "2026-04-01",
        "accepted_by_stakeholder_id": "stk_7Hpx9WxY",
        "accepted_at": 1745539200,
        "ip": "203.0.113.42",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4)"
      },
      {
        "slug": "formation_creates_tax_obligations",
        "version": "2026-04-01",
        "accepted_by_stakeholder_id": "stk_7Hpx9WxY",
        "accepted_at": 1745539200,
        "ip": "203.0.113.42",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4)"
      },
      {
        "slug": "not_legal_advice",
        "version": "2026-01-01",
        "accepted_by_stakeholder_id": "stk_7Hpx9WxY",
        "accepted_at": 1745539200,
        "ip": "203.0.113.42",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4)"
      },
      {
        "slug": "not_tax_advice",
        "version": "2026-01-01",
        "accepted_by_stakeholder_id": "stk_7Hpx9WxY",
        "accepted_at": 1745539200,
        "ip": "203.0.113.42",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4)"
      }
    ]
  }'

Response:

HTTP/1.1 202 Accepted
Content-Type: application/json
Matter-Request-Id: req_Bb2cDd3E

{
  "id": "ent_Nq3KcAbc",
  "object": "entity",
  "state": "submitted",
  "submitted_at": 1745539200,
  "filing_id": "flg_2x7Vc3Mn",
  "disclaimer": {
    "version": "2026-01-01",
    "text": "Matter is a software platform, not a law firm. Matter does not provide legal, tax, or securities advice. The customer is solely responsible for the legal and tax consequences of this action and should consult qualified professionals before proceeding.",
    "text_url": "https://mattermode.com/legal/disclaimer/2026-01-01"
  }
}

The terminal outcome (entity.registered or entity.rejected) arrives via webhook. See the lifecycle reference.

Common mistakes

Mistake	What happens	Fix
Reusing the original `Idempotency-Key` on retry	`409 idempotency_key_reused_with_different_body` — the body changed when you added `acknowledgements[]`.	Mint a new UUID for the retry.
Setting `accepted_by_stakeholder_id` to an `agt_…` identity	`422 invalid_request` — agents are not natural persons and cannot acknowledge.	Set it to a `stk_…` ID for a Stakeholder on the entity.
Hardcoding ack text client-side	Silent drift when slugs are versioned.	Always pull canonical text from `GET /v1/acknowledgements`.
Using a stale acknowledgement (older than 90 days)	`422 acknowledgement_required` returns again with the same slugs in `required[]`.	Re-present the ack to the stakeholder and capture a fresh `accepted_at`.
Setting `accepted_at` in the future or far in the past	`422 invalid_request` — `accepted_at` must be within 5 minutes of server time.	Use the actual moment of affirmative click. Do not pre-fill from a saved draft.

Acknowledgements — the full slug catalog, request shape, expiry, and standing acceptance semantics.
Legal basis — how acknowledgements satisfy UETA §14 on Rail 2 agent signatures.
Disclaimers — the DisclosurePacket returned by disclosure_packet_url.
Errors — the common RFC 7807 envelope and the full error catalog.
Idempotency — why you need a fresh Idempotency-Key on retry.

acknowledgement_required

When it fires

Response shape

Triggering the error

Recovery

Fetching canonical text

Resolved retry

Common mistakes

On this page

acknowledgement_required

When it fires

Response shape

Triggering the error

Recovery

Fetching canonical text

Resolved retry

Common mistakes

On this page