---
title: "Estimate assignment cost"
method: POST
path: "/v1/documents/{documentId}/assignments/estimate-cost"
tags: ["Assignments"]
---

# Estimate assignment cost

`POST /v1/documents/{documentId}/assignments/estimate-cost`

## Request

- Base URL: `https://api.assinafy.com.br`
- URL: `https://api.assinafy.com.br/v1/documents/{documentId}/assignments/estimate-cost`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Api-Key`

Estimate the cost of creating an assignment without creating it, returning a cost breakdown and the current account balances. Signer IDs are not required — only the verification/notification method affects cost. Each assignment consumes 1 document from the plan allowance; if exhausted, an extra document is charged from credits (`needs_extra_document` = true). `blocking_reason` may be `PendingPayment`, `InsufficientDocuments` or `InsufficientCredits`.

### Pricing

Per-unit costs (in credits) used to build the estimate:

| Item | Cost |
|------|------|
| Extra document | 1 credit |
| Email notification | 0 credits |
| WhatsApp notification | 0.45 credits |
| Digital certificate signature (per signer) | 0.5 credits |
| Identity document verification (per signer) | depends on the plan, see the table below |

| Plan | Price per signer |
|------|------------------|
| Free | 1.5 credits |
| Standard | 1 credit |
| Pro | 0.5 credits |
| Other plans and enterprise contracts | 0.25 credits |

`Email` and `Whatsapp` verification are not priced separately — their only line in the `breakdown` is their notification. A `Whatsapp`-verified signer therefore shows up as a WhatsApp notification, because that channel is mandatory for that verification method. A `DigitalCertificate` signer adds the digital-certificate signature cost **on top of** its notification cost; it appears in the `breakdown` under the `SignatureDigitalCertificate` code. An `IdDocumentFaceMatchBasic` signer likewise adds your plan's verification price on top of its notification, under the `VerificationIdDocumentFaceMatchBasic` code.

[Copy as Markdown](https://api.assinafy.com.br/v1/docs/markdown?method=post&path=%2Fv1%2Fdocuments%2F%7BdocumentId%7D%2Fassignments%2Festimate-cost) [Open in ChatGPT](https://chatgpt.com/?q=Read%20the%20API%20documentation%20at%20https%3A%2F%2Fapi.assinafy.com.br%2Fv1%2Fdocs%2Fmarkdown%3Fmethod%3Dpost%26path%3D%252Fv1%252Fdocuments%252F%257BdocumentId%257D%252Fassignments%252Festimate-cost%20and%20help%20me%20integrate%20this%20endpoint.) [Open in Claude](https://claude.ai/new?q=Read%20the%20API%20documentation%20at%20https%3A%2F%2Fapi.assinafy.com.br%2Fv1%2Fdocs%2Fmarkdown%3Fmethod%3Dpost%26path%3D%252Fv1%252Fdocuments%252F%257BdocumentId%257D%252Fassignments%252Festimate-cost%20and%20help%20me%20integrate%20this%20endpoint.)

## Path parameters

- `documentId` string, required

## Request body

- object
  - `method` 'virtual' | 'collect': Send the method you will create the assignment with. With `collect`, a `DigitalCertificate` signer returns `400`, because certificate signing works only on `virtual` assignments.
  - `signers` object[]: Required for `virtual`; each entry may be `{}` to default to Email.
    - `verification_method` 'Email' | 'Whatsapp' | 'DigitalCertificate' | 'IdDocumentFaceMatchBasic': Verification method to price. `Whatsapp` forces the WhatsApp notification, so it prices at 0.45 credits per signer; `DigitalCertificate` adds the per-signer signature cost on top of its notification, and with `method: collect` returns `400` (certificate signers sign only virtual assignments). `IdDocumentFaceMatchBasic` requires its account feature, requires the signer to have a valid CPF in `government_id`, and is charged your plan's per-signer verification price on top of its notification.
    - `notification_methods` string[]: The notification channel to price — exactly one per signer, subject to the same pairing rules as **Create assignment**. `Whatsapp` costs 0.45 credits per signer. Omit it to have it inferred from `verification_method`.
  - `entries` object[]: Required for `collect`.

## Response `200`

Cost estimate and balances

- object: Standard success wrapper. Operations add their own `data`.
  - `status` integer: HTTP status code, mirrored in the body.
  - `message` string: Human-readable message; empty on success.
  - `data` CostEstimate: Cost breakdown for an assignment plus current account balances. `credits` is the sum of `breakdown` (notifications, digital-certificate signatures and identity checks). `total_credits` is what the send will take from the credit balance: `credits`, plus `extra_document_cost` when `needs_extra_document` is true. The extra document is not a `breakdown` line.
    - `documents` integer: Documents consumed (always 1).
    - `credits` number: Sum of the `breakdown` costs: notifications, digital-certificate signatures and identity checks. Does not include the extra document.
    - `needs_extra_document` boolean: True when the plan's document allowance is exhausted and an extra document will be charged from credits.
    - `extra_document_cost` number: Credits for one extra document. Charged only when `needs_extra_document` is true.
    - `total_credits` number: Credits the send will consume: `credits`, plus `extra_document_cost` when `needs_extra_document` is true.
    - `breakdown` CostEstimateBreakdownItem[]
      - `code` string
      - `name` string
      - `cost` number
      - `quantity` integer
      - `unit_cost` number
    - `document_balance` number: Documents left in the plan.
    - `credit_balance` number: Credits available.
    - `has_sufficient_resources` boolean
    - `blocking_reason` 'PendingPayment' | 'InsufficientDocuments' | 'InsufficientCredits', nullable
    - `message` string, nullable

## Other responses

- `400`: One or more fields failed validation.
- `401`: Missing or invalid credentials.
- `500`: Unexpected server error.

## Changes

- **2026-10-15** `da98836f863b`: 1 info
  - added the new `IdDocumentFaceMatchBasic` enum value to the request property `signers/items/verification_method`

[Operation history](https://skmtc.dev/assinafy/apis/assinafy-api-reference/changes/v1/documents/:documentId/assignments/estimate-cost/post.md)

---

[API](https://skmtc.dev/assinafy/apis/assinafy-api-reference.md) - [All operations](https://skmtc.dev/assinafy/apis/assinafy-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/assinafy/apis/assinafy-api-reference/revisions/f7da81a5567e?raw)