> ## Documentation Index > Fetch the complete documentation index at: https://docs.privue.ai/llms.txt > Use this file to discover all available pages before exploring further. # Send a contract > Send a verification waiting on its signatures a contract of one of the contract workflows it is signed on. The verification fills in what the offer says it fills in, you set the rest in `values`, and the contract goes to its signers, each sent their link by SMS or email as the contract workflow says. Each signer signs with Aadhaar eSign. Once a contract of every contract workflow in the verification's `offered_contracts` is signed, the verification completes. A contract workflow its version offers on a `condition` the run does not meet is refused with `409`. One contract of each contract workflow can be out with its signers at a time; withdraw it to send another. One that ends unsigned, by its links running out, a signer failing the Aadhaar checks or being withdrawn, leaves the verification waiting, so send another or reject the verification. On a verification whose version has `features.stamp_paper` on, each contract goes with a stamp paper as its first page: give it in `stamp_paper`, or leave it out to send again the one the last contract of that contract workflow on the verification went with. Each send uses a contract credit whether or not the contract is signed, and restarts the verification's retention window. Your note and the stamp paper are kept with the contract as sent. Asking again after an answer you did not receive sends nothing twice. Where the contract of that contract workflow already out carries the same values, note and stamp paper, it is answered with `200` rather than `201`, and nothing is sent, spent or recorded; a send carrying anything else while one is out is refused with `409`. ## OpenAPI ````yaml /verification/api-reference/openapi.json post /verifications/{verification_id}/contracts openapi: 3.1.0 info: title: Verify with Privue description: >- Start identity-and-business verifications and read the results. There are three ways to run one, and a verification reads the same whichever it was. Every workflow declares which it is for as its `mode`, and a workflow is one of them and never more. **Hosted.** You create a verification with the user's mobile number, email, or both, and receive a journey URL, which we send to every contact you gave on a workflow that sends invitations. They work through the steps your workflow configures, on our screens, and submit. Use this when the person being verified is reachable and holds their own documents. **Staged.** You create a verification, upload each document you hold against the step it answers, and ask for the checks to run. They take longer than a request should be held open, so you read the result from a callback or by polling. Use this when documents reach you over time, or when you want them kept on the record to download later. **Instant.** You send the whole submission in one request. The checks run before it answers, so the reply is the finished record. The documents are read as they arrive and stored nowhere. Use this when you hold everything already and want the answer in the call you made. Whichever it was, you read the whole record: every step, its state, what it collected, and why anything did not pass. An instant verification hands you that record in its reply; for the other two, poll the verification or register a callback endpoint and be told when it is submitted. Across your whole account you can list the workflows configured for you, count your verifications by status, and page through the records behind a count. Every error response has the shape `{"code": "...", "detail": "..."}`. Branch on `code`: several causes share a status, and `detail` is written for a person reading a log rather than for code. Treat a code you do not recognise as the status it arrived at. version: 0.1.0 servers: - url: https://api.verify.privue.ai description: Production security: [] tags: - name: Workflows description: >- The workflows configured for your account. Read one to see its mode, the documents it asks for, and how each step is answered over the API: the slots its documents go in and the values it takes. - name: Verifications description: >- Starting a verification, ending one, clearing one to run the same subject again, and purging one. Shared by both modes. A start answers 201 when it created the verification and 200 when the subject already had one, so a duplicate is visible from the status code alone. - name: Hosted workflows description: >- For a workflow the person being verified walks themselves. Start a verification with their mobile number, email, or both; on a workflow that sends invitations we send them the journey URL. You can also hand it to them yourself, or open it for them from inside your own app with a handoff. - name: Staged workflows description: >- For a workflow you build up from documents you already hold. Upload each file against the step and slot it answers, withdraw one you got wrong, then ask for the checks to run and read the result when they have. Nobody is sent anywhere. - name: Instant workflows description: >- For a workflow answered in the request that asks it. Send the whole submission at once and read the finished record in the reply. Nothing is kept of the documents and nothing is left open to come back to. - name: Contracts description: >- Contracts a hosted verification is signed on once you approve it, on a version that offers them. Preview one, send it with the values you set, follow each signer, remind or withdraw it, and download what was signed. The verification completes once a contract of each it is offered is signed. - name: Results description: >- Reading what a verification came to: one record, a page of them, counts across your account, and links to the files it holds. paths: /verifications/{verification_id}/contracts: post: tags: - Contracts summary: Send a contract description: >- Send a verification waiting on its signatures a contract of one of the contract workflows it is signed on. The verification fills in what the offer says it fills in, you set the rest in `values`, and the contract goes to its signers, each sent their link by SMS or email as the contract workflow says. Each signer signs with Aadhaar eSign. Once a contract of every contract workflow in the verification's `offered_contracts` is signed, the verification completes. A contract workflow its version offers on a `condition` the run does not meet is refused with `409`. One contract of each contract workflow can be out with its signers at a time; withdraw it to send another. One that ends unsigned, by its links running out, a signer failing the Aadhaar checks or being withdrawn, leaves the verification waiting, so send another or reject the verification. On a verification whose version has `features.stamp_paper` on, each contract goes with a stamp paper as its first page: give it in `stamp_paper`, or leave it out to send again the one the last contract of that contract workflow on the verification went with. Each send uses a contract credit whether or not the contract is signed, and restarts the verification's retention window. Your note and the stamp paper are kept with the contract as sent. Asking again after an answer you did not receive sends nothing twice. Where the contract of that contract workflow already out carries the same values, note and stamp paper, it is answered with `200` rather than `201`, and nothing is sent, spent or recorded; a send carrying anything else while one is out is refused with `409`. operationId: send_verifications__verification_id__contracts_post parameters: - name: verification_id in: path required: true schema: type: string format: uuid title: Verification Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SendContractRequest' responses: '200': description: The contract already out, as this send asked again. content: application/json: example: id: 5e0c9a41-7b2d-4f68-a3c1-9d8e2f60b7a4 verification_id: 3f2504e0-4f89-41d3-9a0c-0305e82c3301 run: 1 contract_workflow: dealer-agreement name: Dealer agreement status: pending sent_at: '2026-08-10T16:12:40' expires_at: '2026-08-24T16:12:40' withdrawal_asked_at: null settled_at: null values: dealer_name: Asha Traders Private Limited gstin: 27AABCA1234F1Z5 credit_limit: 5,00,000 start_date: 1 November 2026 note: Credit limit as agreed with the regional head signers: - name: Asha Rao mobile: '9876543210' email: asha@ashatraders.example status: pending signed_at: null link: >- https://contracting-v2.signzy.app/b2ee4ca5-8c22-468c-9e9a-cb00e2562fa7/main failure: null attempts: 0 aadhaar: null messages: - kind: signing-link channel: sms sent_at: '2026-08-10T16:12:41' delivered: true tries: 1 detail: Message successfully delivered to the user stamp_paper: null sent_document: sha256: >- 0ca1d2c5c03e9bed744a4c3d18b6e2f71a9c05d4e83b27f6a1d9c4e05b72f3a8 size_bytes: 29412 signed_files: null callback: null schema: $ref: '#/components/schemas/ContractRecord' '201': description: The contract, out with its signers. content: application/json: example: id: 5e0c9a41-7b2d-4f68-a3c1-9d8e2f60b7a4 verification_id: 3f2504e0-4f89-41d3-9a0c-0305e82c3301 run: 1 contract_workflow: dealer-agreement name: Dealer agreement status: pending sent_at: '2026-08-10T16:12:40' expires_at: '2026-08-24T16:12:40' withdrawal_asked_at: null settled_at: null values: dealer_name: Asha Traders Private Limited gstin: 27AABCA1234F1Z5 credit_limit: 5,00,000 start_date: 1 November 2026 note: Credit limit as agreed with the regional head signers: - name: Asha Rao mobile: '9876543210' email: asha@ashatraders.example status: pending signed_at: null link: >- https://contracting-v2.signzy.app/b2ee4ca5-8c22-468c-9e9a-cb00e2562fa7/main failure: null attempts: 0 aadhaar: null messages: - kind: signing-link channel: sms sent_at: '2026-08-10T16:12:41' delivered: true tries: 1 detail: Message successfully delivered to the user stamp_paper: null sent_document: sha256: >- 0ca1d2c5c03e9bed744a4c3d18b6e2f71a9c05d4e83b27f6a1d9c4e05b72f3a8 size_bytes: 29412 signed_files: null callback: null schema: $ref: '#/components/schemas/ContractRecord' '401': description: |- The API key is missing, malformed, or revoked. The code is `unauthenticated`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: unauthenticated detail: Missing or malformed Authorization header '402': description: >- The workflow has no contract credits left. Read the workflow's `contract_credits` to see where they went, and contact us to add more. The code is `contract-credits-exhausted`. content: application/json: example: code: contract-credits-exhausted detail: >- no contract can be sent because workflow 'merchant-onboarding' has no contract credits left (200 used); contact us to add more schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- The workflow belongs to the other environment. An API key is for `uat` or for `production` and reaches only that environment's workflows. Or the key is valid but not enrolled for verifications, or not set up for exactly one of `uat` and `production`, in which case ask us to reissue it. The code is one of `environment-mismatch` or `client-not-enrolled`. content: application/json: example: code: environment-mismatch detail: >- workflow 'merchant-onboarding' is production and this request is for uat schema: $ref: '#/components/schemas/ErrorResponse' '404': description: >- No verification with that id exists on your account, or the version it runs offers no contract workflow under that key. The code is one of `verification-not-found` or `contract-workflow-not-found`. content: application/json: example: code: verification-not-found detail: >- version 3 of this verification's workflow offers no contract workflow 'dealer-agreement' schema: $ref: '#/components/schemas/ErrorResponse' '409': description: >- The verification is not waiting on its contracts' signatures, has expired, is not signed on this contract workflow, or already has a contract of it out with its signers or signed on its current run. The code is one of `verification-not-signable`, `verification-expired` or `contract-not-sendable`. content: application/json: example: code: verification-not-signable detail: >- a contract of this contract workflow is already out with its signers; withdraw it to send another schema: $ref: '#/components/schemas/ErrorResponse' '422': description: >- The contract cannot be sent as drawn up. The detail names every fault: a value you set that is missing, empty or not yours to set, a date not given as `YYYY-MM-DD` or not on the calendar, a value the verification does not hold, a signer without what the contract workflow asks of them, a value that would print the contract wrongly, such as one too long for its place, or a stamp paper that is missing, not wanted, not base64, over 20 MB, locked with a password, or not a PDF of one page or a JPEG or PNG image. Or the request body is not valid. The code is one of `contract-refused` or `request-invalid`. content: application/json: example: code: contract-refused detail: >- value 'credit_limit': required; value 'gstin': filled from the verification, so the sender cannot set it schema: $ref: '#/components/schemas/ErrorResponse' '429': description: |- The API key is rate limited. Retry after a pause. The code is `rate-limited`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: rate-limited detail: 'Unauthorized: RATE_LIMITED' '500': description: >- Signing contracts is not set up for your account. Nothing was changed. Contact us to have the workflow's configuration put right. The code is `workflow-misconfigured`. content: application/json: example: code: workflow-misconfigured detail: the agreement could not be sent schema: $ref: '#/components/schemas/ErrorResponse' '503': description: >- Signzy, which contracts are signed on, could not be reached, or API keys could not be checked right now. Nothing was changed; try again. The code is one of `esign-unavailable` or `auth-unavailable`. content: application/json: example: code: esign-unavailable detail: Signzy could not be reached, so nothing was sent; try again schema: $ref: '#/components/schemas/ErrorResponse' security: - HTTPBearer: [] components: schemas: SendContractRequest: properties: contract_workflow: type: string maxLength: 64 pattern: ^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$ title: Contract Workflow description: >- The contract workflow to send, one of those the verification's version offers. values: additionalProperties: type: string maxLength: 2000 type: object title: Values description: >- A value for each variable the offer leaves to you, by its name in `open`: every one of them, except on a contract filled from a form, which needs only those its form requires and one of each group its preview names in `required_one_of`. A value of nothing but spaces counts as not given. One named in `dates` is a date as `YYYY-MM-DD`, which the contract prints as `12 April 2100`. The verification fills in the rest, and naming one of those is refused. note: anyOf: - type: string maxLength: 1000 minLength: 1 - type: 'null' title: Note description: >- Your own words about this contract, for whoever reads it after you. Fixed once sent, and deleted with everything the user provided once the verification expires or you purge it. stamp_paper: anyOf: - $ref: '#/components/schemas/StampPaperUpload' - type: 'null' description: >- The stamp paper the contract goes out with, on a verification whose version has `features.stamp_paper` on, and refused on any other. The contract opens with it as its first page, turned the way up it is viewed, fitted to an A4 page, and marked with what it goes with, in the wording and at the place your workflow is set up with. Leave it out to send again the stamp paper the last contract of this contract workflow on the verification went with, which the preview's `stamp_paper.last_sent` names. A stamp paper is good for one contract, so a file identical to one that went with any signed contract of yours is refused, given again or left out, including once that contract's verification has expired or been purged. additionalProperties: false type: object required: - contract_workflow title: SendContractRequest description: >- What sending a contract takes: which one, the values you set, and a note of your own. examples: - contract_workflow: dealer-agreement note: Credit limit as agreed with the regional head values: credit_limit: 5,00,000 start_date: '2026-11-01' ContractRecord: properties: id: type: string format: uuid title: Id description: The contract's id. verification_id: type: string format: uuid title: Verification Id description: The verification it was sent on. run: type: integer minimum: 1 title: Run description: >- Which run of the verification it was sent on: 1 for the first, one more after each reset. A run is signed on its own contracts alone, so one sent before a reset counts for nothing after it. contract_workflow: type: string title: Contract Workflow description: The contract workflow it was drawn up from. name: type: string title: Name description: What its signers were sent it called. status: $ref: '#/components/schemas/ContractStatus' description: >- pending while it is with its signers; withdrawing once you asked for it back, until it is taken back, which waits while a signer is part way through signing and in which time it can still be signed; signed once every signer has signed and its signed document is kept; expired once its signing links ran out first; failed once a signer ran out of attempts at the Aadhaar checks; withdrawn once it was taken back. Every status but pending and withdrawing is final. sent_at: type: string format: date-time title: Sent At description: When it was sent. expires_at: type: string format: date-time title: Expires At description: When its signing links stop working, if it is not signed first. withdrawal_asked_at: anyOf: - type: string format: date-time - type: 'null' title: Withdrawal Asked At description: >- When it was asked to be withdrawn: by you, by rejecting or resetting its verification, or by its verification expiring. Null where it never was. A contract asked to be withdrawn can still end signed, where its signers finished first. settled_at: anyOf: - type: string format: date-time - type: 'null' title: Settled At description: When it reached its final status. Null while it is out. values: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Values description: >- Every value of its template, as sent: the ones the verification filled in and the ones you set. A contract drawn from a form records each input it was filled with: text as given, an address on one line, and anything else, such as a number, its nominees or a yes or no, as JSON. Null once the verification has expired. note: anyOf: - type: string - type: 'null' title: Note description: >- Your note, as sent. Null where you wrote none, and once the verification has expired. signers: anyOf: - items: $ref: '#/components/schemas/ContractSignerRecord' type: array - type: 'null' title: Signers description: >- Everyone who signs it, in the order they sign. Null once the verification has expired. stamp_paper: anyOf: - $ref: '#/components/schemas/StampPaperRecord' - type: 'null' description: >- The stamp paper it went with, as you sent it, held for you to download. Null on a workflow without stamp paper, and once the verification has expired. sent_document: anyOf: - $ref: '#/components/schemas/KeptFileRecord' - type: 'null' description: >- The contract as it went to its signers, held for you to download, with the hash to check a download against. Null until the contract is first read, which follows the send within moments and at most a few minutes, and once the verification has expired. signed_files: anyOf: - $ref: '#/components/schemas/SignedFilesRecord' - type: 'null' description: >- Its signed document and audit certificate, held for you to download, each with the hash to check a download against. Null until it is signed, and once the verification has expired. callback: anyOf: - $ref: '#/components/schemas/CallbackRecord' - type: 'null' description: >- How the callback its final status owes you ended: `contract.signed`, `contract.expired`, `contract.failed` or `contract.withdrawn`. Null until it settles, and on every contract of a workflow with no callback endpoint registered. type: object required: - id - verification_id - run - contract_workflow - name - status - sent_at - expires_at - withdrawal_asked_at - settled_at - values - note - signers - stamp_paper - sent_document - signed_files - callback title: ContractRecord description: One contract sent on a verification, as it stands. ErrorResponse: properties: code: $ref: '#/components/schemas/ErrorCode' description: >- What went wrong. Branch on this rather than on the status code, which several causes share, and never on `detail`. Treat a code you do not recognise as the status it arrived at: codes are added as new causes become reachable, and an existing one never changes meaning. detail: type: string title: Detail description: >- What went wrong, in words, naming the workflow, verification, step or field at fault where one is. Written for a person reading a log rather than for code to read, so it is not stable and nothing should be matched against it. type: object required: - code - detail title: ErrorResponse description: The envelope every failure is answered in. StampPaperUpload: properties: filename: type: string maxLength: 255 minLength: 1 title: Filename description: The file's name, kept with the contract. content_type: type: string enum: - application/pdf - image/jpeg - image/png title: Content Type description: >- The file's MIME type, matching how its content is written: a PDF of one page, or a JPEG or PNG image. content: type: string maxLength: 27962028 minLength: 1 title: Content description: The file itself, base64-encoded, up to 20 MB. additionalProperties: false type: object required: - filename - content_type - content title: StampPaperUpload description: A stamp paper, sent with a contract. ContractStatus: type: string enum: - pending - withdrawing - signed - withdrawn - expired - failed title: ContractStatus description: >- Where a contract sent on a verification stands; every status but pending and withdrawing is final. ContractSignerRecord: properties: name: type: string title: Name description: The name the contract is made out to them in. mobile: anyOf: - type: string - type: 'null' title: Mobile description: >- Their mobile number, which their link went to by SMS. Null where none was sent. email: anyOf: - type: string - type: 'null' title: Email description: >- Their email address, which their link went to by email. Null where none was sent. status: $ref: '#/components/schemas/SignerStatus' description: >- pending until they sign; signed once they have; failed while their last attempt at the Aadhaar checks failed, which they may try again; cancelled once they ran out of attempts, which fails the contract. signed_at: anyOf: - type: string format: date-time - type: 'null' title: Signed At description: When they signed. Null until they have. link: anyOf: - type: string - type: 'null' title: Link description: >- Where they sign, for you to hand them yourself. They are also sent it. Null once the contract has settled. failure: anyOf: - type: string - type: 'null' title: Failure description: Why their last attempt failed, on a failed or cancelled signer. attempts: type: integer title: Attempts description: >- How many times they opened their link and tried to sign. Each attempt that reached the Aadhaar checks is an eSign, whether or not it passed. aadhaar: anyOf: - $ref: '#/components/schemas/SignedAadhaarRecord' - type: 'null' description: Whose Aadhaar they signed with. Null until they sign. messages: items: $ref: '#/components/schemas/SignerMessageRecord' type: array title: Messages description: >- Every message sent them, in the order they went. Empty until the contract is first read. type: object required: - name - mobile - email - status - signed_at - link - failure - attempts - aadhaar - messages title: ContractSignerRecord description: 'One signer of a contract: who it went to, and where they stand.' StampPaperRecord: properties: filename: type: string title: Filename description: The file's name, as you sent it. content_type: type: string title: Content Type description: >- The file's MIME type: `application/pdf`, `image/jpeg` or `image/png`. sha256: type: string title: Sha256 description: The SHA-256 of the file, in hex, to check a download against. size_bytes: type: integer title: Size Bytes description: The file's size in bytes. type: object required: - filename - content_type - sha256 - size_bytes title: StampPaperRecord description: The stamp paper a contract went with, as you sent it. KeptFileRecord: properties: sha256: type: string title: Sha256 description: >- The SHA-256 of the file, in hex, as Signzy stated it and as the file held was checked against. Hash what you download and compare. size_bytes: type: integer title: Size Bytes description: The file's size in bytes. type: object required: - sha256 - size_bytes title: KeptFileRecord description: One of a contract's files, as it is held for you. SignedFilesRecord: properties: signed_document: $ref: '#/components/schemas/KeptFileRecord' description: The contract as every signer signed it. audit_certificate: $ref: '#/components/schemas/KeptFileRecord' description: Signzy's certificate of who signed it, when and how. type: object required: - signed_document - audit_certificate title: SignedFilesRecord description: The two files a signed contract left. CallbackRecord: properties: status: $ref: '#/components/schemas/CallbackStatus' description: >- delivered once your endpoint accepted the callback; failed once every attempt at it was spent without one being accepted. settled_at: type: string format: date-time title: Settled At description: When the callback was accepted, or when the attempts ran out. reason: anyOf: - type: string - type: 'null' title: Reason description: >- Why no attempt was accepted, on a failed callback: what your endpoint last answered, or that it was never sent, through a fault on our side. Null on a delivered one. type: object required: - status - settled_at - reason title: CallbackRecord description: How the callback for this verification ended. ErrorCode: type: string enum: - unauthenticated - client-not-enrolled - rate-limited - auth-unavailable - environment-mismatch - request-invalid - body-unreadable - page-cursor-invalid - window-invalid - request-too-large - not-found - method-not-allowed - internal-error - workflow-not-found - workflow-version-not-found - workflow-not-runnable - workflow-not-walkable - workflow-misconfigured - context-incomplete - context-value-invalid - mobile-required - email-required - journey-fields-refused - return-url-not-allowed - reference-taken - verification-not-found - verification-not-open - verification-expired - invitations-off - invitation-throttled - not-invited - nothing-to-remind - reminder-throttled - verification-not-reviewable - verification-not-reopenable - contracts-out - verification-not-signable - run-in-progress - credits-exhausted - resets-exhausted - contract-credits-exhausted - live-limit-reached - step-not-found - step-not-reopenable - step-not-ready - step-invalid - document-not-found - document-not-stored - document-too-large - document-type-not-allowed - document-locked - contract-workflow-not-found - contract-not-found - contract-not-sendable - contract-refused - contract-settled - contract-not-remindable - contract-files-not-kept - contract-withdrawal-pending - esign-unavailable - identity-unavailable title: ErrorCode description: >- What went wrong, as a value to branch on. Published vocabulary, stated here rather than shared with any other product of ours: these are read by integrations we do not control, so a name here means what it says for as long as the endpoint answering it exists. One code names one cause, so a status carrying several causes is told apart by the code and never by the message. Codes are added as new causes become reachable; an integration therefore treats an unrecognised code as the status it arrived at. SignerStatus: type: string enum: - pending - signed - failed - cancelled title: SignerStatus description: Where one signer stands. SignedAadhaarRecord: properties: name: type: string title: Name description: The name on the Aadhaar. year_of_birth: type: string title: Year Of Birth description: The year of birth on it. gender: type: string title: Gender description: The gender on it. pincode: type: string title: Pincode description: The pincode on it. state: type: string title: State description: The state on it. uid_last_four: type: string title: Uid Last Four description: The last four digits of the Aadhaar number. type: object required: - name - year_of_birth - gender - pincode - state - uid_last_four title: SignedAadhaarRecord description: Who the Aadhaar a signer signed with belongs to, as eSign read it. SignerMessageRecord: properties: kind: $ref: '#/components/schemas/MessageKind' description: >- signing-link for their link to sign, when their turn came and with each reminder; confirmation for the one telling them they signed; audit-certificate for the certificate, once everyone signed; other for any other. channel: type: string title: Channel description: 'How it went: `sms` or `email`.' sent_at: type: string format: date-time title: Sent At description: When it was last tried. delivered: type: boolean title: Delivered description: Whether that try was delivered. tries: type: integer title: Tries description: How many times it was tried. detail: anyOf: - type: string - type: 'null' title: Detail description: How the last try went, in Signzy's words, where it said. type: object required: - kind - channel - sent_at - delivered - tries - detail title: SignerMessageRecord description: One message sent a signer over one channel. CallbackStatus: type: string enum: - delivered - failed title: CallbackStatus description: >- How the hand-off to the client ended. Absent while none has been attempted, or none is owed. MessageKind: type: string enum: - signing-link - confirmation - audit-certificate - other title: MessageKind description: What a message Signzy sent a signer was. securitySchemes: HTTPBearer: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.