Developer reference · v1

API quickstart

Upload an invoice, retain its job ID and retrieve the structured result through the published Number7 AI v1 API.

Published contract guidance · Reviewed 8 September 2026

1. Authenticate on your server.

Keep the API key in a server-side secret. Use the base URL https://api.number7ai.com/api/v1. Start with one non-sensitive test invoice and the credentials supplied for your account.

Authentication header

Authorization: Bearer <YOUR_API_KEY>

Never embed the key in browser JavaScript or an exported collection.

2. Upload an invoice.

Invoice upload · cURL

curl --fail-with-body --request POST \
  'https://api.number7ai.com/api/v1/upload?document.type=invoice&document.version=v1' \
  --header "Authorization: Bearer $N7_API_KEY" \
  --form 'file=@invoice.pdf' \
  --form 'fileName=invoice.pdf' \
  --form 'fileType=application/pdf'

Carry this identifier forwarddata.jobId

Read it from the upload response and persist it before continuing. The acknowledgment means a job was accepted, not that processing has finished.

3. Retrieve the result.

Result lookup · cURL

curl --fail-with-body \
  'https://api.number7ai.com/api/v1/results/YOUR_JOB_ID' \
  --header "Authorization: Bearer $N7_API_KEY"

Replace YOUR_JOB_ID with the returned identifier. Check data.fileStatus in the response. Poll approximately every 20 seconds with a bounded timeout, or use completion webhooks.

Published state	Meaning	Next action
`uploading`, `processing`, `scanning`, `ai_processing`	Intermediate status	Keep waiting within the agreed timeout.
`done`	Result available	Retrieve and validate the business data.
`failed`	Processing failed	Handle the documented failure.

The full structured business-data response depends on your agreed contract. Check contract availability before implementing a consumer.

4. Apply your business controls.

A completed extraction job is not an authorization to post or pay. Validate the returned data against your required accounting fields and policy; retain the original document and job identifier with downstream work.

Handle request and job errors Review the integration boundary