Approvals API reference

What is an approval request?

An approval request asks a person to say yes to one send. The agent names a quote, and the server copies what the quote fixes into the request. That is the document and its hash, the destination, the sender and the amount. The answer returns that copy under bound. The request expires with the quote.

The summary of the create operation ends with "grants nothing". A pending request cannot send a fax. Only an approved one can, once, for the quote it was made from.

How does an agent ask?

POST /v1/approval-requests with a quote_id opens a request of kind send. It needs approval:request, which agent keys carry. The answer has the id, the status, the kind and who asked.

The same operation opens a request of kind help. The body then carries a message and can name a fax_job_id. The schema says the message is shown as data: a person reads it, and the server never acts on it.

Who can approve or reject?

POST /v1/approval-requests/{approval_id}/approve and /reject need approval:decide. The summary of the approve operation names the two ways to hold it. One is a fresh session, which means a person who signed in or proved it again a short time ago. The other is an independent API credential, which means a different API key from the one that asked. An agent key is never issued the scope.

Both take a reason. Rejecting records why, and the requester can read it. The approvals guide has the codes a later send can be refused with.

How does the agent learn the decision?

GET /v1/approval-requests/{approval_id} returns the request with its status, decided_at, decided_by and the reason. An approved request is what POST /v1/faxes takes as approval_id. After the send, consumed_by_job_id names the fax that used it.

GET /v1/approval-requests lists requests with the pending ones first. It filters by status and pages with cursor and limit. Both reads need approval:read.

Can an approval be taken back?

POST /v1/approvals/{approval_id}/revoke withdraws an approval that nobody has used yet. It needs approval:decide, like the decision itself. After a revoke the agent has to quote and ask again. An approval a fax has consumed cannot be revoked. Cancel the fax in the faxes group when it has not ended.

What is the integration review read?

GET /v1/integration-reviews/{org_id}/{environment}/{operation_id}/{binding_id} returns the approval request that one review binding names, in the same shape as the other reads. It takes a signed-in session only, with approval:read. The organization and the environment in the path have to be the ones the session is looking at. An API key is refused.

What does a send need besides an approval?

Nothing more from this group. A live send needs either an approved request or a delegated policy that allows it. Test keys send in the sandbox without either. The approval is checked again at the send. A changed document, destination, sender or amount no longer matches what was approved, and the send is refused.

curl https://api.faxforagents.com/v1/approval-requests \
  -H "Authorization: Bearer ffa_test_..."

curl https://api.faxforagents.com/v1/approval-requests \
  -X POST \
  -H "Authorization: Bearer ffa_test_..." \
  -H "Content-Type: application/json" \
  -d '{}'

curl https://api.faxforagents.com/v1/approval-requests/APPROVAL_ID \
  -H "Authorization: Bearer ffa_test_..."

curl https://api.faxforagents.com/v1/approval-requests/APPROVAL_ID/approve \
  -X POST \
  -H "Authorization: Bearer ffa_test_..." \
  -H "Content-Type: application/json" \
  -d '{}'

curl https://api.faxforagents.com/v1/approval-requests/APPROVAL_ID/reject \
  -X POST \
  -H "Authorization: Bearer ffa_test_..." \
  -H "Content-Type: application/json" \
  -d '{}'

curl https://api.faxforagents.com/v1/approvals/APPROVAL_ID/revoke \
  -X POST \
  -H "Authorization: Bearer ffa_test_..." \
  -H "Content-Type: application/json" \
  -d '{}'

curl https://api.faxforagents.com/v1/integration-reviews/ORG_ID/ENVIRONMENT/OPERATION_ID/BINDING_ID