Skip to content
AssinaJá

Create a document from your own PDF over the API

This is material for whoever integrates AssinaJá with another program. It covers creating a document from a PDF of yours, without a template. You need an API key; the full reference is behind Open API documentation, under Settings → Developers.

The three steps

Section titled “The three steps”
  1. Ask for an upload address: GET /api/public/v1/Document/GenerateSignedUploadUrl. The answer carries uploadUrl and documentPublicId; the address is valid for 1 hour.
  2. Upload the PDF to uploadUrl with a PUT, with the headers x-ms-blob-type: BlockBlob and Content-Type: application/pdf.
  3. Create the document: POST /api/public/v1/Document/CreateDocument, with the documentPublicId from step 1. The answer carries documentId.

The document is built in the background. Send an Idempotency-Key header with a value of your own (a UUID, for example): if the same request arrives again within 24 hours with the same key, you get the same documentId and no second document is created.

A valid body

Section titled “A valid body”
{
  "documentPublicId": "<documentPublicId from step 1>",
  "emailSubject": "Please sign the contract",
  "emailMessage": "Here is the contract we discussed.",
  "signerRecipients": [
    {
      "name": "Maria Silva",
      "email": "maria@example.pt",
      "phoneNumber": "+351912345678",
      "signatureType": "OTPSMS",
      "protectionMode": "None",
      "order": 1,
      "documentRecipientSignatureLocations": [
        { "pageNumber": 2, "x": 10, "y": 80, "width": 30, "height": 8 }
      ]
    }
  ]
}

signatureType takes Simple, SimpleInitials, OTPSMS, IdConfirmation, CMD, CMDSCAP or LDC.

Where the signature boxes go

Section titled “Where the signature boxes go”

Each signer’s boxes go in signerRecipients[].documentRecipientSignatureLocations.

Do not use signatureLocations. That field exists in the signer, but it is what the document details return when you read them (GET /Document/{id}). In a create request it is refused with SIGNATURE_LOCATIONS_WRONG_FIELD.

Each box has:

  • pageNumber — 1 for the first page;
  • x, y, width and height — all required, as a percentage of the page (0 to 100), measured from the top-left corner;
  • x + width no more than 100, and y + height no more than 100.

A signer with no boxes is not invited to sign.

Errors the request returns straight away

Section titled “Errors the request returns straight away”

These come back as 400 with { code, message, detail }, and no document is created. detail names the field, for example signerRecipients[1].phoneNumber.

code When What to do
NO_SIGNER_RECIPIENTS signerRecipients is empty. Add at least one signer.
SIGNATURE_LOCATIONS_WRONG_FIELD The boxes came in signatureLocations and documentRecipientSignatureLocations is empty. Move them to documentRecipientSignatureLocations.
INVALID_SIGNATURE_LOCATION A box is incomplete or goes past the edge of the page. Check the box named in detail against the rules above.
SIGNER_PHONE_REQUIRED A signer with signatureType OTPSMS has no phoneNumber. Add the phone number, or choose another signature type.
NO_SIGNATURE_LOCATIONS No signer has a box. Give at least one signer a box.

The last two only apply when the document is going to be sent. If the organisation has Documents created outside the browser start as drafts turned on, the document stays a draft for a person to finish, and the phone and the boxes are checked when it is sent.

Following the document after it is created

Section titled “Following the document after it is created”

While the document is still being built, GET /api/public/v1/Document/{id} answers 409 with code document_processing. Ask again a little later.

Some problems can only be found once the PDF is open — a box on a page the PDF does not have, for example. In that case GET /Document/{id}, PATCH /Document/{id}/Publish, GET /Document/{id}/SignUrl and GET /Document/{id}/SignUrls all answer 400 with:

  • code: DOCUMENT_CREATION_FAILED;
  • message: “The creation of the document with id N failed: …”, followed by the reason;
  • detail: the original code — for example SIGNER_PHONE_REQUIRED, VALIDATION_ERROR or INTERNAL_ERROR.

An internal error shows only as INTERNAL_ERROR, with no further detail. An older document may answer with no reason after the message and no detail.

That document is final — asking again will not change the answer. To try again, start from step 1: a new GenerateSignedUploadUrl, a new upload (the documentPublicId you used is spent) and a new Idempotency-Key.

Sending a draft

Section titled “Sending a draft”

A document that started as a draft is sent with PATCH /api/public/v1/Document/{id}/Publish — the method is PATCH, not POST. Publishing sends the document to the signers.

Section titled “Related”