Skip to main content

KYC documents

A mandate goes to review accompanied by its supporting documents: the Kbis extract of the mandating company, the signer's identity document, and the proof of their signing capacity. These documents are the mandate's KYC (Know Your Customer) documents (Electronic invoicing mandates): when they are required and any are missing, submission for review responds 422. The requirement depends on the workspace - the mandate's kyc_required field carries the value, and it is false for accounting-firm and tax-representative workspaces, whose mandates go to review with no KYC document at all. An active mandate gates writes to the national directory (National directory). This page covers the document reference, uploading PDF files, and responding to requests for additional documents.

What Scribee does for you​

  • Creates the three standard documents in requested status as soon as the mandate is created: you declare nothing, you upload a file on each.
  • Checks each file at upload - PDF only, under 50 MB - and refuses with an immediate 422 rather than letting the review fail on an unreadable document.
  • Guarantees one document per standard type and per mandate: a second declaration of the same type is refused.
  • Materializes each review request for an additional document as a document in the same list, in requested status with its description: your integration follows a single rule - upload a file on every requested document.

Document kinds​

kindLabelOrigin
kbis_extractKbis extractCreated by Scribee when the mandate is created
identity_paperIdentity documentCreated by Scribee when the mandate is created
signing_capacity_proofProof of signing capacityCreated by Scribee when the mandate is created
additionalAdditional documentCreated by Scribee when the review requests a document, or by you (step 3) - description required

This enum is distinct from the invoice supporting-documents one (Supporting documents): kbis_extract is not kbis, identity_paper is not identity_document. Never merge the two references in your integration.

The three standard types do not apply to every mandate: each mandate carries the boolean kyc_required field, which is false for workspaces that are an accounting firm or a tax representative. On these mandates, no standard document is created or required; only the requested-documents rule applies (no document left in requested).

Statuses​

statusLabelWho sets it
requestedRequestedScribee - the document awaits its file
uploadedUploadedYou, by uploading the file (steps 2 and 3)

A document is created in requested and moves to uploaded on upload. Upload replays: a new call replaces the file and leaves the document in uploaded.

Step 1: list the expected documents​

This call is a read: it creates nothing and transmits nothing externally - the read scope is enough. When a mandate whose kyc_required is true is created, the three standard documents already exist in requested status.

curl https://app.scribee.tech/api/v1/mandates/YOUR_MANDATE_ID/kyc_documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response, abbreviated to the fields useful here:

{
  "data": [
    { "id": 512, "kind": "kbis_extract", "status": "requested", "description": null, "has_file": false },
    { "id": 513, "kind": "identity_paper", "status": "requested", "description": null, "has_file": false },
    { "id": 514, "kind": "signing_capacity_proof", "status": "requested", "description": null, "has_file": false }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total_pages": 1,
    "total_count": 3
  }
}

Each document also carries mandate_id, created_at, and updated_at. The list is paginated (page, per_page) and sorts by sort_by (kind, status, or created_at - created_at by default) and sort_order (asc or desc - desc by default). include=mandate adds the carrying mandate to each document (id, mandate_number, state). A document can also be read individually, without going through the mandate: GET /api/v1/kyc_documents/{id}.

Step 2: upload a requested document's file​

This call attaches the file to the document and moves it to uploaded status. Nothing is transmitted externally: the file is kept by Scribee for the mandate's review. The file is a PDF (application/pdf) under 50 MB, sent as multipart/form-data in the file field; the write scope is required.

Sending a file to a document that already holds one is safe. If the new file is rejected - a format other than PDF, or a size above 50 MB - the call answers 422 and the document stays exactly in its prior state: the file already accepted and the status are kept. Only an accepted file replaces the previous one.

curl -X POST https://app.scribee.tech/api/v1/kyc_documents/512/upload \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@extrait-kbis.pdf;type=application/pdf"

Abbreviated response:

{
  "data": {
    "id": 512,
    "kind": "kbis_extract",
    "status": "uploaded",
    "has_file": true
  }
}

Repeat the call on documents 513 and 514 with the corresponding files.

Step 3: add a document on your side​

This call creates a document and attaches its file in a single multipart/form-data submission; the document is born directly in uploaded status, and nothing is transmitted externally. It serves to provide a document that the review has not requested - an additional document with its description required - or to recreate a deleted standard document (only one per type and per mandate). kind and file are required; a read write token is required.

curl -X POST https://app.scribee.tech/api/v1/mandates/YOUR_MANDATE_ID/kyc_documents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "kyc_document[kind]=additional" \
  -F "kyc_document[description]=Attestation de pouvoir du signataire" \
  -F "kyc_document[file]=@attestation-pouvoir.pdf;type=application/pdf"

Response 201, abbreviated:

{
  "data": {
    "id": 515,
    "kind": "additional",
    "status": "uploaded",
    "description": "Attestation de pouvoir du signataire",
    "has_file": true
  }
}

Step 4: delete a pending document​

This call permanently deletes the document. It only targets documents in requested status: once a file is uploaded, the document can no longer be deleted - its file is replaced instead (step 2). A read write token is required. Deleting a standard document does not lift the requirement: when kyc_required is true, submission always requires the three types - recreate it via step 3.

curl -X DELETE https://app.scribee.tech/api/v1/kyc_documents/512 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response 204, with no body.

Respond to a request for additional documents​

When the review needs an additional document, the mandate moves back to incomplete and new additional documents appear in the list, in requested status, each with a description that specifies the expected document. Your work does not change: relist the mandate's documents (step 1), upload a file on each requested document (step 2), then submit the mandate for review again.

What happens next​

  • KYC completeness gates the mandate's submission for review: when kyc_required is true, each of the three standard types must be uploaded, and in every case no document may remain in requested - otherwise submission responds 422. This condition is independent of the mandate's signature: the two are checked separately before submission (Electronic invoicing mandates).
  • Once the mandate is approved, the documents remain readable (GET) with their status.

Errors and edge cases​

Validation failures respond 422 with error: "unprocessable_entity", the message "La validation a échoué" and the cause in details.base. Base your handling on the HTTP status, never on the message text (API conventions).

422: deletion refused​

DELETE only targets documents in requested status:

{
  "error": "unprocessable_entity",
  "code": "validation_failed",
  "message": "La validation a échoué",
  "details": {
    "base": ["Seuls les documents demandés peuvent être supprimés"]
  }
}

422: invalid file or attributes​

In the same format, in details.base:

MessageCauseWhat you do
Un fichier est requisfile missing from creation or uploadattach the file as multipart/form-data
File doit être un fichier PDFa MIME type other than application/pdfconvert the document to PDF
File doit être inférieur à 50 Mofile too largecompress the PDF under 50 MB
Description est requise pour les documents complémentaireskind is additional without descriptionadd the document's description
Kind a déjà été prisa second standard document of the same type on the mandateupload onto the existing document (step 2)
Kind n'est pas inclus(e) dans la listekind outside the four values in the kinds tablefix the value

403: insufficient scope​

Reads on this page require read. Creation and upload require write; deletion accepts destroy or write. A token that does not carry the scope the call requires responds:

{
  "error": "forbidden",
  "message": "Vous n'êtes pas autorisé à effectuer cette action"
}

404 Not Found​

The mandate or the document does not exist, belongs to a workspace outside your application's scope, or belongs to a workspace whose IPv4 allowlist denies your request's address - on these endpoints a denied address produces this 404, not the 403 described in the API conventions:

{
  "error": "not_found",
  "message": "La ressource demandée est introuvable"
}

400: unusable kyc_document object​

On creation (step 3), parameter reading only keeps kind and description inside the kyc_document object. A submission carrying neither - for example a multipart/form-data reduced to the sole kyc_document[file] field, or with no kyc_document object at all - never reaches validation: the response is a 400 in the usual error envelope, with error set to bad_request and the message "Le corps de la requête est manquant ou mal formé":

{
  "error": "bad_request",
  "message": "Le corps de la requête est manquant ou mal formé"
}

Always send kind.

400 Bad Request: page beyond the last​

The list from step 1 is paginated and responds 400 beyond the last page, as everywhere else: API conventions.