Skip to main content

Send documents by API

Post a file to a flow and fetch the result, or have it sent to you by webhook.

Create a key

Open Settings, and under Workspace open For developers. Select Create key. Give the key a name, such as "Invoice system", and select Create key again.

A box shows the key once. Copy it, store it somewhere safe, then select I've saved it. We cannot show it again.

If this fails

If creating the key is refused, you are not a workspace admin. Ask an admin to create it.

Copy the flow's API address

Open the flow, go to the Arrives step and open For developers. Select Copy beside the address.

You have an address that ends in /documents. Every call below goes to it.

Send a file

Post the file as a part named file, with your key in the X-ProcuLink-Key header. Add an Idempotency-Key so a retry never makes a second document.

curl -X POST "https://api.example.com/api/v1/flows/FLOW_ID/documents" \
  -H "X-ProcuLink-Key: YOUR_KEY" \
  -H "Idempotency-Key: march-invoice-0001" \
  -F "file=@invoice.pdf"

The answer is 201 and a short summary. Keep its id. The document appears on the flow's Documents page with the status Received.

If this fails

The answer names the problem in error. A 401 means the key is wrong or revoked. A 415 lists the file types the flow accepts. The full list is in the API reference.

Fetch the result

Reading takes a short while. Ask for the document by its id.

curl "https://api.example.com/api/v1/documents/DOCUMENT_ID" \
  -H "X-ProcuLink-Key: YOUR_KEY"

The answer holds the document's status, the values we read, any checks that flagged something, and what was sent. Ask again until status is needs_review, ready, sent or one of the failed statuses.

Optional: get told by webhook

Instead of asking again and again, let us call you. Under For developers, enter it in Web address to call when a document is read or sent. Enter a signing secret if you want to check that calls come from us. Select Save and send a test.

Your address receives a document.test call, and the card says "The test went through." After that you receive a call when a document is read, fails to read, is sent or fails to send. Check the signature as shown in the API reference.

If this fails

The card shows why the test failed, for example that the address answered with an error status, or could not be reached. Your address must answer 2xx and be reachable from the internet.

Good to know

A file you send by API counts as a document, the same as an upload. A call we refuse does not create a document.