{ "openapi": "3.1.0", "info": { "title": "Priva6 API", "version": "1.0.0", "summary": "Send documents for legal e-signature.", "description": "Send a Priva6 document (DPA, NDA, BAA, SCC…) for signature to a client, from your own tools.\n\nAuthenticate with an API key created by an organization admin in Priva6 (Settings → API keys), in the `X-API-Key` header. The key is shown once when it is created; keep it secret, on your server only. Each key is limited to 100 sends per hour.\n\nThe client receives an email with a secure signing link, and is saved in the organization's clients: a new client, or the existing client with the same email (case-insensitive), updated with the details sent. Every send is recorded in the document's audit trail, with the API key's name. Optionally, `sender_email` names the team member sending it: they are recorded as the sender, as when sending from Priva6, and receive the signed document once everyone has signed.", "contact": { "name": "Priva6", "url": "https://priva6.com" } }, "servers": [ { "url": "https://api.priva6.com/functions/v1/api", "description": "Production" } ], "security": [ { "apiKeyHeader": [] } ], "paths": { "/documents/{documentId}/send": { "post": { "operationId": "sendDocument", "summary": "Send a document for signature", "description": "Sends the latest revision of the document to the client, who is created or updated as a client of the organization. The subject, message and link expiry default to the document's settings (its first email); the document's reminders follow, to the client if they haven't signed yet. `sender_email` optionally sets the team member sending it.", "tags": [ "Documents" ], "parameters": [ { "name": "documentId", "in": "path", "required": true, "description": "The document's ID, as shown on the document page in Priva6. The ID of any revision (or the document key) can be used: the latest revision is always sent.", "schema": { "type": "string", "format": "uuid" }, "example": "3f1c9a52-7b4e-4c1d-9a2f-5e8b6d0c1a23" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendRequest" }, "examples": { "minimal": { "summary": "Required fields only", "value": { "name": "Jane Doe", "email": "jane@acme.com" } }, "full": { "summary": "With the client's details and a custom message", "value": { "name": "Jane Doe", "email": "jane@acme.com", "company": "Acme SAS", "vat": "FR12345678901", "registration_number": "123 456 789 RCS Paris", "website": "https://acme.com", "position": "Data Protection Officer", "department": "Legal", "phone": "+33 1 23 45 67 89", "address": "1 rue de la Paix", "zipcode": "75002", "city": "Paris", "country": "FR", "email_subject": "Your DPA with Fernand SAS", "email_body": "Hello {client},\n\nHere is {document} for signature: {link}", "expiry_days": 7, "sender_email": "alice@fernand.io" } } } } } }, "responses": { "201": { "description": "Sent: the contact received the signing email.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/Archived" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/EmailFailed" } } } } }, "components": { "securitySchemes": { "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "`X-API-Key: p6_…` with an API key of your organization." } }, "schemas": { "Client": { "type": "object", "description": "The organization's client, as saved after the send.", "required": [ "id", "name", "email" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "company": { "type": [ "string", "null" ] }, "vat": { "type": [ "string", "null" ] }, "registration_number": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "department": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "position": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "zipcode": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 code." } } }, "Signature": { "type": "object", "description": "The signature request that was created.", "required": [ "id", "status", "expires_at", "document_id", "revision" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending" ], "description": "Always \"pending\" right after sending." }, "expires_at": { "type": "string", "format": "date-time", "description": "When the signing link expires." }, "document_id": { "type": "string", "format": "uuid", "description": "The ID of the revision that was sent (the latest)." }, "revision": { "type": "integer", "minimum": 1, "description": "The revision number that was sent." } } }, "SendResult": { "type": "object", "required": [ "signature", "client" ], "properties": { "signature": { "$ref": "#/components/schemas/Signature" }, "client": { "$ref": "#/components/schemas/Client" } }, "example": { "signature": { "id": "8d2e4f10-1c3b-4a5d-8e7f-9a0b1c2d3e4f", "status": "pending", "expires_at": "2026-10-29T15:04:05.000Z", "document_id": "3f1c9a52-7b4e-4c1d-9a2f-5e8b6d0c1a23", "revision": 2 }, "client": { "id": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e", "name": "Jane Doe", "email": "jane@acme.com", "company": "Acme SAS", "vat": "FR12345678901", "registration_number": "123 456 789 RCS Paris", "website": "https://acme.com", "position": "Data Protection Officer", "department": "Legal", "phone": "+33 1 23 45 67 89", "address": "1 rue de la Paix", "zipcode": "75002", "city": "Paris", "country": "FR" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "What went wrong, in plain English." } } }, "SendRequest": { "type": "object", "description": "The client to send the document to, and optionally the email and link settings. Optional client fields that are empty or omitted leave the existing client's details unchanged.", "required": [ "name", "email" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Full name.", "example": "Jane Doe" }, "email": { "type": "string", "format": "email", "maxLength": 254, "description": "Where the signing link is sent; also identifies the client (case-insensitive). The signer can't change it.", "example": "jane@acme.com" }, "company": { "type": "string", "maxLength": 200, "description": "Company name.", "example": "Acme SAS" }, "vat": { "type": "string", "maxLength": 50, "description": "Company VAT number.", "example": "FR12345678901" }, "registration_number": { "type": "string", "maxLength": 50, "description": "Company registration number (e.g. SIREN / RCS, company number).", "example": "123 456 789 RCS Paris" }, "website": { "type": "string", "maxLength": 200, "description": "Company website.", "example": "https://acme.com" }, "department": { "type": "string", "maxLength": 100, "description": "Department in the company.", "example": "Legal" }, "phone": { "type": "string", "maxLength": 30, "description": "Phone number.", "example": "+33 1 23 45 67 89" }, "position": { "type": "string", "maxLength": 200, "description": "Position in the company.", "example": "Data Protection Officer" }, "address": { "type": "string", "maxLength": 300, "description": "Company address: street and number.", "example": "1 rue de la Paix" }, "zipcode": { "type": "string", "maxLength": 20, "description": "Company address: zip / postal code.", "example": "75002" }, "city": { "type": "string", "maxLength": 100, "description": "Company address: city.", "example": "Paris" }, "country": { "type": "string", "pattern": "^[A-Za-z]{2}$", "description": "Company address: ISO 3166-1 alpha-2 country code (case-insensitive).", "example": "FR" }, "email_subject": { "type": "string", "maxLength": 200, "description": "Subject of the first email (default: the document's). Placeholders: {client}, {document}, {organization}, {link}, {expiry_date}.", "example": "Please sign: {document}" }, "email_body": { "type": "string", "maxLength": 10000, "description": "Plain-text message of the first email (default: the document's). Placeholders: {client}, {document}, {organization}, {link}, {expiry_date}; the link is added at the end if not placed.", "example": "Hello {client},\n\nPlease sign {document}: {link}" }, "expiry_days": { "type": "integer", "minimum": 1, "maximum": 365, "description": "How many days the signing link stays valid (default: the document's).", "example": 14 }, "sender_email": { "type": "string", "format": "email", "maxLength": 254, "description": "Email of the team member sending the document (case-insensitive): a member of the API key's organization who has joined it. Recorded as the sender, as when sending from Priva6, and receives the signed document and its audit trail once everyone has signed. Default: none (the API key only).", "example": "alice@yourcompany.com" } } } }, "responses": { "BadRequest": { "description": "Invalid request: the body isn't JSON, `name` or `email` is missing or invalid, a field is too long, `country` isn't a known ISO code, `expiry_days` is out of range, or `sender_email` isn't a member of the organization (or hasn't joined it yet).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "A valid \"email\" is required" } } } }, "Unauthorized": { "description": "Missing, invalid or revoked API key (`X-API-Key` header).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Missing or invalid API key" } } } }, "NotFound": { "description": "No document with this ID in the API key's organization (or an unknown path).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Document not found" } } } }, "MethodNotAllowed": { "description": "Only POST is supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Use POST" } } } }, "Archived": { "description": "The document is archived: it can't be sent until it is unarchived in Priva6.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "This document is archived" } } } }, "RateLimited": { "description": "More than 100 sends in the last hour with this API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Rate limit: 100 sends per hour per API key" } } } }, "ServerError": { "description": "Unexpected error. Nothing was sent; you can retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Something went wrong. Please try again later." } } } }, "EmailFailed": { "description": "The email could not be sent. No signature request is left behind; you can retry. (The client may have been saved in the clients.)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "The email could not be sent: …" } } } } } }, "tags": [ { "name": "Documents", "description": "Send documents for signature." } ] }