Introduction

Base URL

https://app.procurementexpress.com

The ProcurementExpress API gives your systems the same purchasing data and actions as the web app: raise and approve purchase orders, manage budgets, suppliers and products, capture and approve invoices, record payments, and get notified through webhooks when something changes.

Two API versions

The API is served in two versions that share the same resources. Most endpoints exist in both; a few are only in one (see V3 and V1).

Build new integrations on V3. V1 remains fully supported for existing integrations and for the endpoints that only exist there.

How to read this reference

• Every endpoint shows its availability as badges: V3 V1 (a dashed badge means the endpoint does not exist in that version).
• The tabs at the top of the dark column switch every example between cURL · V3, cURL · V1, Ruby · V3 and Ruby · V1.
• Examples use these environment variables:

export PEX_ACCESS_TOKEN="<V3 access token from POST /oauth/token>"
export PEX_AUTH_TOKEN="<V1 authentication_token from POST /api/v1/login>"
export PEX_COMPANY_ID="<your company id>"

• Every request and response in this reference is real. Each example was sent to the current ProcurementExpress release in a test company called Acme Corporation (company id 20000) and the response is shown as returned, with secrets replaced by placeholders and long lists shortened. The ids and values you see belong to that test company; yours will differ. A few endpoints depend on an outside service (SAM.gov, AI document extraction, email delivery); their examples were recorded without that service, and the endpoint's description explains the full behaviour.
• A machine-readable OpenAPI 3.1 description and a Postman collection are generated from the same verified examples.

Getting help

Questions, or something here that doesn't match what you see? Email support@procurementexpress.com and include the X-Request-Id response header of the request in question.

Quickstart

Make your first V3 call in four steps. You need a ProcurementExpress user with the company admin role to register the OAuth application; the API then acts as that user.

1. Register an OAuth application

1. Sign in to ProcurementExpress as a company admin.
2. Open Integrations and choose Custom OAuth Applications → Integrate, then Add OAuth Application.
3. Enter a name (for example ERP integration). Leave Redirect URI and Scopes blank: server-to-server integrations use the client credentials grant, which needs neither.
4. Save and copy the Client ID and Client Secret. The secret is shown only once (it is stored hashed). If you lose it, use Renew secret on the application, which invalidates the old one.

2. Request an access token

curl -X POST "https://app.procurementexpress.com/oauth/token" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=$PEX_CLIENT_ID" \
  --data-urlencode "client_secret=$PEX_CLIENT_SECRET"

# V1 uses a user's API token instead of OAuth.
curl -X POST "https://app.procurementexpress.com/api/v1/login" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "jane.doe@example.com",
  "password": "<password>"
}'

require "rest-client"
require "json"

response = RestClient.post(
  "https://app.procurementexpress.com/oauth/token",
  grant_type: "client_credentials",
  client_id: ENV.fetch("PEX_CLIENT_ID"),
  client_secret: ENV.fetch("PEX_CLIENT_SECRET")
)
access_token = JSON.parse(response.body).fetch("access_token")

require "rest-client"
require "json"

# V1 uses a user's API token instead of OAuth.
response = RestClient.post(
  "https://app.procurementexpress.com/api/v1/login",
  { email: "jane.doe@example.com", password: ENV.fetch("PEX_PASSWORD") }.to_json,
  { content_type: :json }
)
auth_token = JSON.parse(response.body).fetch("authentication_token")

V3 response 200 OK:

{
  "access_token": "<access-token>",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "public",
  "created_at": 1792576011
}

The token is valid for expires_in seconds (2 hours). Client credentials tokens have no refresh token: when a token expires (the API answers 401 with WWW-Authenticate: Bearer … error="invalid_token"), request a new one the same way. Cache the token and reuse it until it expires instead of requesting one per call. See Authentication for the V1 sign-in flow, two-factor authentication and token revocation.

3. Find your company id

Every resource call needs the app_company_id header. List the companies the token's user belongs to (this call does not need the header):

curl "https://app.procurementexpress.com/api/v3/companies" \
  -H "Authorization: Bearer $PEX_ACCESS_TOKEN"

curl "https://app.procurementexpress.com/api/v1/companies" \
  -H "authentication_token: $PEX_AUTH_TOKEN"

require "rest-client"
require "json"

response = RestClient.get(
  "https://app.procurementexpress.com/api/v3/companies",
  { "Authorization" => "Bearer #{ENV.fetch('PEX_ACCESS_TOKEN')}" }
)
puts JSON.parse(response.body).map { |c| [c["id"], c["name"]] }.inspect

require "rest-client"
require "json"

response = RestClient.get(
  "https://app.procurementexpress.com/api/v1/companies",
  { "authentication_token" => ENV.fetch("PEX_AUTH_TOKEN") }
)
puts JSON.parse(response.body).map { |c| [c["id"], c["name"]] }.inspect

Response 200 OK (shortened):

[
  {
    "id": 20000,
    "name": "Acme Corporation",
    "roles": ["companyadmin", "approver", "finance", "teammember"],
    "approval_limit": 1000000.0,
    "membership_archived": false
  }
]

4. Make your first request

List the company's purchase orders:

curl "https://app.procurementexpress.com/api/v3/purchase_orders" \
  -H "Authorization: Bearer $PEX_ACCESS_TOKEN" \
  -H "app_company_id: $PEX_COMPANY_ID"

curl "https://app.procurementexpress.com/api/v1/purchase_orders" \
  -H "authentication_token: $PEX_AUTH_TOKEN" \
  -H "app_company_id: $PEX_COMPANY_ID"

require "rest-client"
require "json"

response = RestClient.get(
  "https://app.procurementexpress.com/api/v3/purchase_orders",
  {
    "Authorization" => "Bearer #{ENV.fetch('PEX_ACCESS_TOKEN')}",
    "app_company_id" => ENV.fetch("PEX_COMPANY_ID")
  }
)
puts JSON.pretty_generate(JSON.parse(response.body))

require "rest-client"
require "json"

response = RestClient.get(
  "https://app.procurementexpress.com/api/v1/purchase_orders",
  {
    "authentication_token" => ENV.fetch("PEX_AUTH_TOKEN"),
    "app_company_id" => ENV.fetch("PEX_COMPANY_ID")
  }
)
puts JSON.pretty_generate(JSON.parse(response.body))

From here:

• Purchase Orders covers creating, approving and receiving orders.
• Webhooks pushes changes to your system instead of polling.
• Requests and Responses explains pagination, dates and request formats; Errors lists every error shape you can receive.

Authentication

Every API request is made as a ProcurementExpress user and in one company. There are two ways to prove who you are:

New integrations should use V3 with the client credentials grant. The OAuth2 password grant is not available to integrations (the token endpoint answers 401 unauthorized_client), and neither is the authorization-code grant, which is reserved for ProcurementExpress's own apps and MCP clients.

1. Create an OAuth application (V3)

A company admin creates the application in the web app under Integrations → Custom OAuth Applications → Integrate (/companies/<company id>/oauth_applications). Give it a name; the redirect URI can be left blank for client credentials. The client secret is shown once, right after creation (it is stored hashed); if it is lost, use Renew secret to issue a new one.

The application is owned by the admin who created it, and every token issued to it acts as that user: it has exactly that user's roles, approval limits and permissions in the company named by app_company_id, and it can address any company that user is a live member of. Create the application from the account you want the integration to act as (many customers use a dedicated "API user").

2. Get an access token

curl https://app.procurementexpress.com/oauth/token \
  -X POST \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=$PEX_CLIENT_ID" \
  --data-urlencode "client_secret=$PEX_CLIENT_SECRET"

The token is valid for 7200 seconds. Client credentials tokens come without a refresh token: when a token expires (any V3 call answers 401 with WWW-Authenticate: Bearer ... error="invalid_token", error_description="The access token expired"), simply request a new one. Every request to /oauth/token mints a new token, so cache the token for its lifetime instead of requesting one per call, and revoke tokens you no longer need (POST /oauth/revoke).

3. Call the API

Header names are case-insensitive. Some proxies drop header names that contain underscores; if yours does, use the hyphenated spellings Authentication-Token and App-Company-Id.

Before any endpoint runs, the API checks the credential and the company, in this order (both versions): credential present and valid → app_company_id present → caller is a member of that company (otherwise 404 Invalid id passed) → membership not archived (401) → company paid up and active (402 Billing Details Required) → 2FA requirement of that company (401 otp_required). See Authentication errors for every response.

Use GET /currentuser to discover the companies the credential can act in: each entry of companies[] tells you whether the membership is archived (membership_archived), whether the company is blocked for billing (is_locked, requests answer 402) or removed (is_removed).

V1 tokens

A V1 authentication_token belongs to the user, not to a device or an integration: every app and script that signs in as the same user shares one token. It is returned only by the sign-in endpoints (login, verify_otp), never by GET /currentuser. It does not expire. POST /api/v1/logout replaces it with a new one, which signs that user out everywhere the old token was used.

Two-factor authentication (2FA / OTP)

A company can require a one-time code at sign-in for all its members (company setting) or for single members. API credentials are user-wide, so the requirement is enforced per request, against the company the request addresses (app_company_id; without that header, against the user's default company employer_id):

• V1 tokens are accepted in a 2FA company only if the token was confirmed with POST /verify_otp after that company's requirement began. Signing in with POST /api/v1/login for an account where any company requires 2FA returns {"otp_sent": true} and e-mails a 6-digit code (valid 5 minutes, 5 wrong attempts burn it); POST /verify_otp with the code returns the token, now marked as OTP-verified.
• V3 client credentials tokens have no user session behind them and are not subject to 2FA: they work in 2FA companies. Protect the client secret accordingly.
• V3 tokens bound to a user (issued to ProcurementExpress's own apps through a browser sign-in) are accepted only if that sign-in passed the second factor after the requirement began.
• Changing the account itself (PUT /currentuser, POST /api_user_update, POST /users/deactivate_account) requires the credential to satisfy every company that requires 2FA, not just the addressed one.

A refused request gets 401 with "otp_required": true:

{
  "error": "Two-factor authentication is required for this company. Sign in again with your one-time code.",
  "otp_required": true,
  "status": 401
}

The fix for a V1 client is to sign in again with login + verify_otp.

Rate limits

Sign-in endpoints are rate limited: POST /api/v1/login, /verify_otp and /resend_otp allow 60 requests per minute per client IP and 20 attempts per account (e-mail) per 15 minutes; reset_password 10 requests per 15 minutes per IP and 3 per hour per e-mail; register 10 per 15 minutes per IP. All /api paths also share a per-IP request budget. Over a limit the API answers 429 (sign-in endpoints with an empty {} body and a Retry-After header). Repeated wrong passwords also lock the account (Devise lockout), after which login keeps answering Invalid email or password.

Localization (`Locale` header)

Error and validation messages are translated when the request carries a Locale header naming an installed locale exactly (case-sensitive, hyphenated):

en (default), es, es-CL, es-MX, fr, de, nl, pt, ru, sk, pl, lv, el, he, hi, af, ja, en-GB, en-insider, it, ko, km, tr, uk, gd.

• A missing or unrecognised value (ES, es_MX, xx) silently uses English.
• Accept-Language and a ?locale= query parameter are ignored.
• Translation coverage varies: some messages stay in English even for supported locales (for example de still returns App company id is nil); messages without a translation in the requested locale are returned in English.
• The locale applies to messages only; field names, enum values and data are never translated.

curl https://app.procurementexpress.com/api/v3/budgets \
  -H "Authorization: Bearer $PEX_ACCESS_TOKEN" \
  -H "Locale: es"
# {"error":"El id de la compañía de la aplicación es nulo","status":401}

The old locale-bundle download (GET /locales/:locale) and the account-existence check (GET /useralreadyregistered) are retired and answer 410 Gone.

Endpoints in this section

Get an access token

curl -X POST "https://app.procurementexpress.com/oauth/token" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=<client-id>" \
  --data-urlencode "client_secret=<client-secret>"

# V3 only: this endpoint has no V1 equivalent.
curl -X POST "https://app.procurementexpress.com/oauth/token" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=<client-id>" \
  --data-urlencode "client_secret=<client-secret>"

require "rest-client"
require "json"

response = RestClient::Request.execute(
  method: :post,
  url: "https://app.procurementexpress.com/oauth/token",
  headers: {

  },
  payload: {
    grant_type: "client_credentials",
    client_id: "<client-id>",
    client_secret: "<client-secret>"
  }
)

puts JSON.pretty_generate(JSON.parse(response.body))

# V3 only: this endpoint has no V1 equivalent.
require "rest-client"
require "json"

response = RestClient::Request.execute(
  method: :post,
  url: "https://app.procurementexpress.com/oauth/token",
  headers: {

  },
  payload: {
    grant_type: "client_credentials",
    client_id: "<client-id>",
    client_secret: "<client-secret>"
  }
)

puts JSON.pretty_generate(JSON.parse(response.body))

V3 response 200 OK:

{
  "access_token": "<access-token>",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "public",
  "created_at": 1792577106
}

Example: json (V3, 200 OK):

{
  "access_token": "<access-token>",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "public",
  "created_at": 1792577121
}

V3 V1 —

Exchange your OAuth application's client id and secret for a V3 bearer access token.

OAuth2 token endpoint. Integrations use the client credentials grant only. The token acts as the user who owns the OAuth application.

• Send the fields as application/x-www-form-urlencoded (shown) or as a JSON object; the client can also authenticate with HTTP Basic (Authorization: Basic base64(client_id:client_secret)) instead of the two body fields.
• The only scope is public (the default; scope can be omitted).
• No refresh token is issued for this grant and tokens are not reused: every call creates a new token valid for 7200 seconds.
• grant_type=password and grant_type=authorization_code are refused for integration applications (unauthorized_client); grant_type=refresh_token is refused as well, because client-credentials tokens have no refresh token.
• The response carries Cache-Control: no-store.
• The endpoint only accepts POST (GET /oauth/token answers 404, or 405 on deployments where the MCP integration is enabled).

HTTP request

Permissions

No user credential. The application must be a confidential (secret-holding) application created by a company admin. Unknown client or wrong secret: 401 invalid_client.

Body parameters (form-encoded)

Response

200 with the token. token_type is always Bearer, expires_in is in seconds, created_at is a Unix timestamp (seconds). Errors use the OAuth2 shape {"error": "...", "error_description": "..."} (the refresh / authorization-code refusals carry only error). A missing grant_type answers 400 invalid_request.

V3 and V1 differences

V3 only. V1 does not use OAuth: V1 clients obtain an authentication_token with POST /api/v1/login. The token endpoint is not under /api, so the path is absolute.

Errors

Check an access token

curl "https://app.procurementexpress.com/oauth/token/info" \
  -H "Authorization: Bearer $PEX_ACCESS_TOKEN"

# V3 only: this endpoint has no V1 equivalent.
curl "https://app.procurementexpress.com/oauth/token/info" \
  -H "Authorization: Bearer $PEX_ACCESS_TOKEN"

require "rest-client"
require "json"

response = RestClient::Request.execute(
  method: :get,
  url: "https://app.procurementexpress.com/oauth/token/info",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch('PEX_ACCESS_TOKEN')}"
  }
)

puts JSON.pretty_generate(JSON.parse(response.body))

# V3 only: this endpoint has no V1 equivalent.
require "rest-client"
require "json"

response = RestClient::Request.execute(
  method: :get,
  url: "https://app.procurementexpress.com/oauth/token/info",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch('PEX_ACCESS_TOKEN')}"
  }
)

puts JSON.pretty_generate(JSON.parse(response.body))

V3 response 200 OK:

{
}

V3 V1 —

Returns 200 while the bearer token is valid and 401 once it is invalid, expired or revoked.

The OAuth2 token-info endpoint. Send the token in the Authorization header. Use the status code to decide whether the token is still usable: 200 means valid, 401 (with WWW-Authenticate: Bearer realm="Doorkeeper", error="invalid_token", ...) means request a new token. The body of the 200 response is currently an empty object; use POST /oauth/introspect if you need the expiry time.

HTTP request

Permissions

Bearer token only (no client credentials, no app_company_id).

Response

200 {} for a valid token. 401 {"error":"invalid_token","error_description":"The access token is invalid","state":"unauthorized"} otherwise.

V3 and V1 differences

V3 only (OAuth). V1 has no equivalent; any V1 call answers 401 for an invalid token.

Errors

Introspect an access token

curl -X POST "https://app.procurementexpress.com/oauth/introspect" \
  --data-urlencode "token=<access-token>" \
  --data-urlencode "client_id=<client-id>" \
  --data-urlencode "client_secret=<client-secret>"

# V3 only: this endpoint has no V1 equivalent.
curl -X POST "https://app.procurementexpress.com/oauth/introspect" \
  --data-urlencode "token=<access-token>" \
  --data-urlencode "client_id=<client-id>" \
  --data-urlencode "client_secret=<client-secret>"

require "rest-client"
require "json"

response = RestClient::Request.execute(
  method: :post,
  url: "https://app.procurementexpress.com/oauth/introspect",
  headers: {

  },
  payload: {
    token: "<access-token>",
    client_id: "<client-id>",
    client_secret: "<client-secret>"
  }
)

puts JSON.pretty_generate(JSON.parse(response.body))

# V3 only: this endpoint has no V1 equivalent.
require "rest-client"
require "json"

response = RestClient::Request.execute(
  method: :post,
  url: "https://app.procurementexpress.com/oauth/introspect",
  headers: {

  },
  payload: {
    token: "<access-token>",
    client_id: "<client-id>",
    client_secret: "<client-secret>"
  }
)

puts JSON.pretty_generate(JSON.parse(response.body))

V3 response 200 OK:

{
  "active": true,
  "scope": "public",
  "client_id": "<client-id>",
  "token_type": "Bearer",
  "exp": 1792584335,
  "iat": 1792577135
}

Example: inactive (V3, 200 OK):

{
  "active": false
}

V3 V1 —

RFC 7662 token introspection - tells whether a token is active, its scope and expiry.

Authenticate as the OAuth application (form fields client_id / client_secret, or HTTP Basic) and pass the token to inspect. An unknown, expired or revoked token answers 200 {"active": false}. Tokens of MCP clients are reported inactive unless the request comes from the MCP client itself.

HTTP request

Permissions

Client authentication required; without it the request answers 400 invalid_request. Authenticating with the inspected token itself as bearer is not accepted (401 invalid_token).

Body parameters (form-encoded)

Response

200. Active tokens: active: true, scope, client_id (the application's UID), token_type, exp and iat (Unix seconds). Inactive: only active: false.

V3 and V1 differences

V3 only (OAuth). V1 does not use OAuth.

Errors

Revoke an access token

curl -X POST "https://app.procurementexpress.com/oauth/revoke" \
  --data-urlencode "token=<access-token>" \
  --data-urlencode "client_id=<client-id>" \
  --data-urlencode "client_secret=<client-secret>"

# V3 only: this endpoint has no V1 equivalent.
curl -X POST "https://app.procurementexpress.com/oauth/revoke" \
  --data-urlencode "token=<access-token>" \
  --data-urlencode "client_id=<client-id>" \
  --data-urlencode "client_secret=<client-secret>"

require "rest-client"
require "json"

response = RestClient::Request.execute(
  method: :post,
  url: "https://app.procurementexpress.com/oauth/revoke",
  headers: {

  },
  payload: {
    token: "<access-token>",
    client_id: "<client-id>",
    client_secret: "<client-secret>"
  }
)

puts JSON.pretty_generate(JSON.parse(response.body))

# V3 only: this endpoint has no V1 equivalent.
require "rest-client"
require "json"

response = RestClient::Request.execute(
  method: :post,
  url: "https://app.procurementexpress.com/oauth/revoke",
  headers: {

  },
  payload: {
    token: "<access-token>",
    client_id: "<client-id>",
    client_secret: "<client-secret>"
  }
)

puts JSON.pretty_generate(JSON.parse(response.body))

V3 response 200 OK:

{
}

V3 V1 —

Revoke (sign out) an access token issued to your application.

RFC 7009 revocation. The token stops working immediately (V3 calls then answer 401 The access token was revoked, introspection reports active: false). Revoking an unknown token also answers 200 {}. A token issued to a different application cannot be revoked (403).

HTTP request

Permissions

Client authentication (client_id + client_secret, or HTTP Basic) is required for confidential applications; without it, or for another application's token: 403 {"error":"unauthorized_client","error_description":"You are not authorized to revoke this token"}.

Body parameters (form-encoded)

Response

200 {} on success (also for an unknown token).

V3 and V1 differences

V3 only (OAuth). The V1 counterpart is POST /api/v1/logout.

Errors

Sign in (V1)

# V1 only: this endpoint has no V3 equivalent.
curl -X POST "https://app.procurementexpress.com/api/v1/login" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "lee.login@example.com",
  "password": "<password>"
}'

curl -X POST "https://app.procurementexpress.com/api/v1/login" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "lee.login@example.com",
  "password": "<password>"
}'

# V1 only: this endpoint has no V3 equivalent.
require "rest-client"
require "json"

response = RestClient::Request.execute(
  method: :post,
  url: "https://app.procurementexpress.com/api/v1/login",
  headers: {
    "Content-Type" => "application/json"
  },
  payload: {
    email: "lee.login@example.com",
    password: "<password>"
  }.to_json
)

puts JSON.pretty_generate(JSON.parse(response.body))

require "rest-client"
require "json"

response = RestClient::Request.execute(
  method: :post,
  url: "https://app.procurementexpress.com/api/v1/login",
  headers: {
    "Content-Type" => "application/json"
  },
  payload: {
    email: "lee.login@example.com",
    password: "<password>"
  }.to_json
)

puts JSON.pretty_generate(JSON.parse(response.body))

V1 response 200 OK:

{
  "id": 4,
  "email": "lee.login@example.com",
  "name": "Lee Login",
  "approver_name": "Lee Login",
  "phone_number": "+15550199",
  "setup_incomplete": false,
  "employer_id": 3,
  "approval_limit": 1000000.0,
  "companies": [
    {
      "id": 3,
      "name": "Lee Workshop",
      "external_user_id": null,
      "membership_archived": false,
      "is_locked": false,
      "is_removed": false,
      "approval_limit": 1000000.0,
      "in_trial": true,
      "trial_expired": false,
      "remaining_trial_days": 365,
      "roles": [
        "companyadmin",
        "approver",
        "finance",
        "teammember"
      ],
      "has_unassigned_budgets": false
    }
  ],
  "roles": null,
  "authentication_token": "<authentication-token>",
  "external_user_id": null
}

Example: slim companies (V1, 200 OK):

{
  "id": 4,
  "email": "lee.login@example.com",
  "name": "Lee Login",
  "approver_name": "Lee Login",
  "phone_number": "+15550199",
  "setup_incomplete": false,
  "employer_id": 3,
  "approval_limit": 1000000.0,
  "companies": [
    {
      "id": 3,
      "name": "Lee Workshop",
      "external_user_id": null,
      "membership_archived": false,
      "is_locked": false,
      "is_removed": false,
      "approval_limit": 1000000.0,
      "in_trial": true,
      "trial_expired": false,
      "remaining_trial_days": 365,
      "roles": [
        "companyadmin",
        "approver",
        "finance",
        "teammember"
      ],
      "has_unassigned_budgets": false
    }
  ],
  "roles": null,
  "authentication_token": "<authentication-token>",
  "external_user_id": null
}

V3 — V1

Exchange e-mail and password for the user's V1 authentication_token.

Validates the password (counting failures towards the Devise lockout).

• No 2FA required anywhere for this account: returns the user object with authentication_token. The existing token is returned (a token is created only if the user has none), so all clients of the same user share it. The token is marked as not OTP-verified.
• Any company or membership of the account requires 2FA: a 6-digit code is generated and e-mailed, and the response is {"otp_sent": true}. Complete the sign-in with POST /verify_otp. Signing in again within 30 seconds re-sends the same code instead of a new one.
• Wrong password, unknown e-mail, locked, deactivated or archived account all answer the same 400 Invalid email or password.

email is matched case-insensitively. Pass slim_companies (any value) to shrink every company except the default one to {id, name, is_removed}. The call also starts a web session (a session cookie is set), which API clients can ignore.

HTTP request

Permissions

Unauthenticated. Rate limited (60/min per IP, 20 per 15 min per account).

Body parameters

Response

200 with the User object plus authentication_token, or 200 {"otp_sent": true} when a one-time code is required.

Side effects

Updates last_sign_in_at / Devise trackable fields; with 2FA, e-mails the code (synchronously, through Postmark).

V3 and V1 differences

V1 only. V3 has no sign-in route: POST /api/v3/login falls through to the catch-all and answers 404 Invalid URL (or 401 without a bearer token). V3 integrations authenticate with POST /oauth/token.

Errors

Verify a one-time code

curl -X POST "https://app.procurementexpress.com/api/v3/verify_otp" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "olivia.otp@example.com",
  "otp_attempt": "628354",
  "slim_companies": "1"
}'

curl -X POST "https://app.procurementexpress.com/api/v1/verify_otp" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "olivia.otp@example.com",
  "otp_attempt": "835374"
}'

require "rest-client"
require "json"

response = RestClient::Request.execute(
  method: :post,
  url: "https://app.procurementexpress.com/api/v3/verify_otp",
  headers: {
    "Content-Type" => "application/json"
  },
  payload: {
    email: "olivia.otp@example.com",
    otp_attempt: "628354",
    slim_companies: "1"
  }.to_json
)

puts JSON.pretty_generate(JSON.parse(response.body))

require "rest-client"
require "json"

response = RestClient::Request.execute(
  method: :post,
  url: "https://app.procurementexpress.com/api/v1/verify_otp",
  headers: {
    "Content-Type" => "application/json"
  },
  payload: {
    email: "olivia.otp@example.com",
    otp_attempt: "835374"
  }.to_json
)

puts JSON.pretty_generate(JSON.parse(response.body))

Response 200 OK, same structure in V3 and V1 (lists shortened to 2 items):

{
  "id": 3,
  "email": "olivia.otp@example.com",
  "name": "Olivia Otp",
  "approver_name": "Olivia Otp",
  "phone_number": "+15550199",
  "setup_incomplete": false,
  "employer_id": 2,
  "approval_limit": 1000000.0,
  "companies": [
    {
      "id": 2,
      "name": "Initech OTP",
      "external_user_id": null,
      "membership_archived": false,
      "is_locked": false,
      "is_removed": false,
      "approval_limit": 1000000.0,
      "in_trial": true,
      "trial_expired": false,
      "remaining_trial_days": 365,
      "roles": [
        "companyadmin",
        "approver",
        "finance",
        "teammember"
      ],
      "has_unassigned_budgets": false
    },
    {
      "id": 6,
      "name": "Initrode Inc (archived member)",
      "external_user_id": null,
      "membership_archived": false,
      "is_locked": false,
      "is_removed": false,
      "approval_limit": 1000000.0,
      "in_trial": true,
      "trial_expired": false,
      "remaining_trial_days": 365,
      "roles": [
        "companyadmin",
        "approver",
        "finance",
        "teammember"
      ],
      "has_unassigned_budgets": false
    }
  ],
  "roles": null,
  "authentication_token": "<authentication-token>",
  "external_user_id": null
}

Example: mixed case email (V3, 400 Bad Request):

{
  "error": "Invalid OTP",
  "status": 400
}

V3 V1

Complete a 2FA sign-in with the e-mailed 6-digit code and receive the V1 authentication_token.

Second step after POST /api/v1/login answered {"otp_sent": true}. On success the code is consumed, the user's token is marked as OTP-verified (it is replaced by a new one if it was issued while the account already required 2FA) and the user object with authentication_token is returned. That token is then accepted in companies that require 2FA.

Codes are valid for 5 minutes; after 5 wrong attempts the code is burned and the user must sign in again. Every failure (wrong, expired or burned code, unknown e-mail, no pending challenge) answers the same 400 Invalid OTP.

HTTP request

Permissions

Unauthenticated. Shares the sign-in rate limits.

Body parameters

Response

200 with the User object including authentication_token.

V3 and V1 differences

Routed in both versions, but V3 has no login, so a challenge can only be started from V1 (or google_login), and V3 verify_otp returns the V1 authentication_token, not an OAuth token. V3 matches email case-sensitively (Olivia.Otp@Example.com answers Invalid OTP in V3, succeeds in V1 - see the extra capture) and ignores slim_companies.

Errors

Resend the one-time code

curl -X POST "https://app.procurementexpress.com/api/v3/resend_otp" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "olivia.otp@example.com"
}'

curl -X POST "https://app.procurementexpress.com/api/v1/resend_otp" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "olivia.otp@example.com"
}'

require "rest-client"
require "json"

response = RestClient::Request.execute(
  method: :post,
  url: "https://app.procurementexpress.com/api/v3/resend_otp",
  headers: {
    "Content-Type" => "application/json"
  },
  payload: {
    email: "olivia.otp@example.com"
  }.to_json
)

puts JSON.pretty_generate(JSON.parse(response.body))

require "rest-client"
require "json"

response = RestClient::Request.execute(
  method: :post,
  url: "https://app.procurementexpress.com/api/v1/resend_otp",
  headers: {
    "Content-Type" => "application/json"
  },
  payload: {
    email: "olivia.otp@example.com"
  }.to_json
)

puts JSON.pretty_generate(JSON.parse(response.body))

Response 200 OK, same structure in V3 and V1:

{
  "otp_sent": true
}

Example: unknown email (V1, 200 OK):

{
  "otp_sent": true
}

V3 V1

Re-send a fresh code for a pending 2FA sign-in.

Always answers {"otp_sent": true}, whether or not the address exists or has a pending challenge, so it cannot be used to probe accounts. The mail is sent in the background, and only when a password (or Google) login started a challenge that has not expired; the new code keeps the earlier wrong-attempt count.

HTTP request

Permissions

Unauthenticated. Shares the sign-in rate limits.

Body parameters

Response

200 {"otp_sent": true}.

Side effects

Emails a new one-time code (sent in the background).

V3 and V1 differences

None - identical request and response.

Sign out (V1)

# V1 only: this endpoint has no V3 equivalent.
curl -X POST "https://app.procurementexpress.com/api/v1/logout" \
  -H "authentication_token: $PEX_AUTH_TOKEN"

curl -X POST "https://app.procurementexpress.com/api/v1/logout" \
  -H "authentication_token: $PEX_AUTH_TOKEN"

# V1 only: this endpoint has no V3 equivalent.
require "rest-client"
require "json"

response = RestClient::Request.execute(
  method: :post,
  url: "https://app.procurementexpress.com/api/v1/logout",
  headers: {
    "authentication_token" => ENV.fetch("PEX_AUTH_TOKEN")
  }
)

puts JSON.pretty_generate(JSON.parse(response.body))

require "rest-client"
require "json"

response = RestClient::Request.execute(
  method: :post,
  url: "https://app.procurementexpress.com/api/v1/logout",
  headers: {
    "authentication_token" => ENV.fetch("PEX_AUTH_TOKEN")
  }
)

puts JSON.pretty_generate(JSON.parse(response.body))

V1 response 200 OK:

{
  "success": true,
  "info": "Logged out"
}

Example: old token rejected (V1, 401 Unauthorized):

{
  "error": "Authentication token is invalid",
  "status": 401
}

V3 — V1

Invalidate the user's V1 authentication_token.

Replaces the user's authentication_token with a new, unpublished one. Because the token is shared by every client of the same user, this signs the user out of all apps and integrations that use the V1 token. The next login returns the new token. No body is needed and app_company_id is not required.

HTTP request

Permissions

A valid authentication_token; missing or invalid token answers 401.

Response

200 {"success": true, "info": "Logged out"}; afterwards the old token answers 401 Authentication token is invalid.

V3 and V1 differences

V1 only (route commented out in V3; POST /api/v3/logout answers 404 Invalid URL). V3 clients revoke their bearer token with POST /oauth/revoke.

Errors

Request a password reset e-mail

curl -X POST "https://app.procurementexpress.com/api/v3/reset_password" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "lee.login@example.com"
}'

curl -X POST "https://app.procurementexpress.com/api/v1/reset_password" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "lee.login@example.com"
}'

require "rest-client"
require "json"

response = RestClient::Request.execute(
  method: :post,
  url: "https://app.procurementexpress.com/api/v3/reset_password",
  headers: {
    "Content-Type" => "application/json"
  },
  payload: {
    email: "lee.login@example.com"
  }.to_json
)

puts JSON.pretty_generate(JSON.parse(response.body))

require "rest-client"
require "json"

response = RestClient::Request.execute(
  method: :post,
  url: "https://app.procurementexpress.com/api/v1/reset_password",
  headers: {
    "Content-Type" => "application/json"
  },
  payload: {
    email: "lee.login@example.com"
  }.to_json
)

puts JSON.pretty_generate(JSON.parse(response.body))

Response 200 OK, same structure in V3 and V1:

{
  "success": "true"
}

Example: unknown email (V3, 200 OK):

{
  "success": "true"
}

V3 V1

E-mail password-reset instructions to an address.

Always answers {"success": "true"} (note: a string), whether or not the address is registered. When it is, Devise reset instructions are e-mailed in the background. Rate limited to 3 requests per e-mail per hour and 10 per IP per 15 minutes.

HTTP request

Permissions

Unauthenticated.

Body parameters

Response

200 {"success": "true"}.

Side effects

Emails the password reset link (sent in the background).

V3 and V1 differences

None - identical request and response.

Authentication errors

curl "https://app.procurementexpress.com/api/v3/budgets" \
  -H "app_company_id: $PEX_COMPANY_ID"

curl "https://app.procurementexpress.com/api/v1/budgets" \
  -H "app_company_id: $PEX_COMPANY_ID"

require "rest-client"
require "json"

response = RestClient::Request.execute(
  method: :get,
  url: "https://app.procurementexpress.com/api/v3/budgets",
  headers: {
    "app_company_id" => ENV.fetch("PEX_COMPANY_ID")
  }
)

puts response.code

require "rest-client"
require "json"

response = RestClient::Request.execute(
  method: :get,
  url: "https://app.procurementexpress.com/api/v1/budgets",
  headers: {
    "app_company_id" => ENV.fetch("PEX_COMPANY_ID")
  }
)

puts JSON.pretty_generate(JSON.parse(response.body))

V3 response 401 Unauthorized (empty body)

V1 response 401 Unauthorized:

{
  "error": "Authentication token is nil",
  "status": 401
}

Example: auth error missing company localized (V3, 401 Unauthorized):

{
  "error": "El id de la compañía de la aplicación es nulo",
  "status": 401
}

V3 V1

The responses every endpoint can give before it runs - credential, company and 2FA checks.

Shown here on GET /budgets, but every authenticated endpoint behaves the same. V1 errors are JSON {"error": "<message>", "status": <code>}. V3 credential errors come from the OAuth layer: empty body with a WWW-Authenticate header; company and 2FA errors are JSON like V1.

Other status codes used across the API: 400 invalid parameters or validation failure (error is a message string, sometimes an array), 401 Unauthorized access when your role may not perform the action, 404 Invalid id passed for an unknown record id and 404 Invalid URL for an unknown path, 410 retired endpoint, 422 some validation failures, 429 rate limited, and 400 {"status":400,"error":"Bad Request"} for a malformed JSON body. Messages follow the Locale header.

HTTP request

Permissions

n/a

Response

See the table.

V3 and V1 differences

V3 credential failures (missing / invalid / expired / revoked token) have an empty body and the reason only in WWW-Authenticate; V1 returns a JSON message. A deactivated user gets a credential error in V1 but, in V3, only the company check refuses it (as "account archived"). MCP tokens exist only in V3 (403). The company and 2FA checks are identical.

Errors

Requests and Responses

Headers

curl "https://app.procurementexpress.com/api/v3/budgets" \
  -H "Authorization: Bearer $PEX_ACCESS_TOKEN" \
  -H "app_company_id: $PEX_COMPANY_ID" \
  -H "Accept: application/json" \
  -H "locale: es"

curl "https://app.procurementexpress.com/api/v1/budgets" \
  -H "authentication_token: $PEX_AUTH_TOKEN" \
  -H "app_company_id: $PEX_COMPANY_ID" \
  -H "Accept: application/json" \
  -H "locale: es"

require "rest-client"

RestClient.get(
  "https://app.procurementexpress.com/api/v3/budgets",
  {
    "Authorization" => "Bearer #{ENV.fetch('PEX_ACCESS_TOKEN')}",
    "app_company_id" => ENV.fetch("PEX_COMPANY_ID"),
    "Accept" => "application/json",
    "locale" => "es"
  }
)

require "rest-client"

RestClient.get(
  "https://app.procurementexpress.com/api/v1/budgets",
  {
    "authentication_token" => ENV.fetch("PEX_AUTH_TOKEN"),
    "app_company_id" => ENV.fetch("PEX_COMPANY_ID"),
    "Accept" => "application/json",
    "locale" => "es"
  }
)

All traffic must use HTTPS. Every response carries an X-Request-Id header; include it when you contact support about a specific call.

Request bodies

Send JSON with Content-Type: application/json. Most write endpoints expect their fields wrapped in the resource name, Rails style, and nested records as *_attributes arrays:

{
  "purchase_order": {
    "supplier_id": 2,
    "purchase_order_items_attributes": [
      { "description": "27-inch 4K monitor", "quantity": 2, "unit_price": 329.99 }
    ]
  }
}

• A missing wrapper (for example posting {"name": "x"} instead of {"department": {"name": "x"}}) answers 400 with {"error": "Required parameter are missing.", "status": 400}.
• Unknown or misspelt fields are silently ignored, not rejected. If a value you sent does not appear in the response, check the field name against the endpoint's parameter table.
• A body that is not valid JSON answers 400 with an empty body.
• The same fields can also be sent form-encoded (purchase_order[supplier_id]=2), which is what file-upload endpoints use with multipart/form-data.

Pagination

List endpoints are paginated with page (1-based) and per_page. Where an endpoint accepts per_page, the allowed values are usually 10, 20, 50 and 100; anything else falls back to the user's own results per page setting (10 by default). Each endpoint's parameter table says what it accepts.

Paginated V3 responses wrap the list and add a meta object:

{
  "budgets": [ { "id": 1, "name": "Engineering Hardware FY26" } ],
  "meta": {
    "current_page": 1,
    "next_page": 2,
    "prev_page": null,
    "total_pages": 4,
    "total_count": 37
  }
}

Keep requesting page = meta.next_page until it is null. Several V1 list endpoints return a bare JSON array with no meta; the endpoint pages show the exact shape for each version. When an endpoint pages without meta, stop when a page returns fewer items than per_page.

Data types

• Parse money with a decimal type, not binary floating point.
• Always honour the offset in ISO timestamps; do not assume UTC.
• Field types are given in each endpoint's tables. A field documented as a Unix timestamp is seconds since the epoch in UTC.

Records and tenancy

• Everything you read or write belongs to the company in app_company_id. Ids of records that are not in that company answer 404 Invalid id passed, and so does an app_company_id the user is not a member of.
• What a user can see and do depends on their roles in that company (companyadmin, approver, finance, teammember). Each endpoint's Permissions section says who may call it and what others get back. Make integration calls as a user whose roles cover the data you need.
• Most resources are archived rather than deleted. Archived records drop out of lists by default and can usually be listed again with a filter.

Retries and idempotency

The API has no idempotency keys. If a POST times out you cannot tell whether it was applied, and retrying it can create a duplicate (for example a second purchase order). Before retrying a create, look the record up (for example list purchase orders filtered by your own reference) and only retry when it is not there. GET requests are always safe to retry. Back off on 429 and 5xx responses (see Rate Limits).

Errors

Error body (V1, and V3 once authenticated)

{
  "error": "Invalid id passed",
  "status": 404
}

V3 with a missing, invalid, expired or revoked access token: empty body

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="Doorkeeper", error="invalid_token", error_description="The access token is invalid"
Content-Length: 0

ProcurementExpress uses conventional HTTP status codes. Errors raised by the API itself have a JSON body with a human-readable error message (translated when you send a locale header) and the status repeated. Some validation failures return the model's messages instead; each endpoint lists the error bodies it was observed to return.

The authentication and company errors every endpoint can return are listed under Authentication errors.

Rate Limits

A throttled request is answered with 429 and plain text:

HTTP/1.1 429 Too Many Requests
Content-Type: text/plain
Retry-After: 3600

Retry later

Requests are rate limited per client IP address. All /api/v1 and /api/v3 calls from one IP share one budget, whichever user or token makes them, so integrations that run several jobs behind one egress IP should coordinate.

When you are throttled the response is 429 Too Many Requests with a Retry-After header giving the seconds until the window resets. For the general API limit the body is the plain text Retry later; for sign-in limits it is an empty JSON object {}. Separately, an account is locked after six failed password attempts; it unlocks automatically after one hour or through the unlock link emailed to the user.

If your integration needs a higher limit, contact support@procurementexpress.com with the IP addresses you call from.

Staying within the limits

• Use Webhooks to learn about new and changed purchase orders and invoices instead of polling lists.
• Cache reference data that rarely changes (departments, budgets, suppliers, tax rates, currencies) and refresh it on a schedule.
• Ask for per_page=100 when walking a list.
• Reuse a V3 access token for its full two-hour lifetime instead of requesting a new one per call.
• On 429, wait for Retry-After seconds. On 5xx, retry GET requests with exponential backoff and jitter; see Retries and idempotency before retrying writes.

Blocked clients

Requests that look like vulnerability scans (for example paths containing wp-admin or /etc/passwd) count against the caller's IP. After 10 of them in a day the IP is blocked for 24 hours and every request gets 403 Forbidden.

V3 and V1

Both versions are served side by side from the same application and the same data: a purchase order created through V1 is immediately visible through V3. They differ in how you authenticate and, for some endpoints, in the shape of the response.

Only in V1: Compliance (policies, scans, evidence packs), Custom Fields management, Suppliers: Approvals, publishing, unpublishing and exporting Approval Flows, and rerunning an invoice's approval flow.

Only in V3: OAuth2 token management, archiving budgets and QuickBooks Online: Item Budget Mappings.

Choosing a version. Use V3 unless you need an endpoint that only exists in V1. An integration can use both, for example V3 for orders and V1 for compliance checks, with the same app_company_id; the V1 token and the V3 OAuth application should then belong to the same user.

Migrating from V1 to V3. Register an OAuth application under the same user your V1 integration signs in as and swap the authentication_token header for Authorization: Bearer …. Then re-check each call against the endpoint's V3 and V1 differences section: records mostly have the same fields, but list envelopes, pagination parameters, filters and some status codes differ.

The table lists every public endpoint and the versions it is available in.

Endpoint availability

Approval Flows

An approval flow is a rule that decides who has to approve a document and in which order. Each flow targets one document type, says which documents it applies to (conditions) and lists one or more steps, each with its own approvers and an approval rule (any one approver, or all of them). When a matching document is submitted, the flow is attached to it and approval requests are sent step by step. Each document a flow was attached to is a run of that flow.

Approval flows replace the classic routing (approvers picked on the PO, budget approvers and approval limits) - see Enabling approval flows below, the switch is company-wide.

Document types

Anatomy of a flow

• Flow conditions (approval_conditions at the top level) decide whether the flow applies to a document. All of them must match (AND). A custom flow must have at least one.
• Steps (approval_steps, ordered by step_no) run one after another. A flow must have at least one step and every step at least one approver.
• Step conditions (approval_steps[].approval_conditions) are optional. A step that has conditions is skipped (treated as completed) unless all of its conditions match - e.g. "add the CFO as a second step only when the gross amount is 10,000 or more". On a PO split into allocations, step conditions are evaluated against the same department/budget allocation that made the flow match; amount conditions always look at the whole PO.
• Approvers (approval_steps[].approval_step_approvers) are individual users - there are no role or group approvers. A user must be an active (non-archived) member of the company, otherwise the save fails with "approval_steps.approval_step_approvers.user_id": ["is invalid"]. The API does not require the approver role.
• Approval rule (all_should_approve):
  • false - any one can approve: every approver of the step is asked at once and the first approval completes the step.
  • true - all must approve: approvers are asked one at a time, in the order they were added, and the step completes when everyone has approved.
• Self approval (self_approval_allowed): when false, the document's creator is skipped if they are an approver in a step. When true and the company setting auto_approve_self_requests is on, the creator's own request is approved automatically.
• Approvers on holiday are covered by their holiday delegate (user.on_holiday in responses).

A rejection by any approver rejects the document and marks all of its runs rejected. When every request of every attached flow is approved, the PO becomes approved.

Conditions

A condition is property + operator + value. Values are always sent as strings.

property is not validated: an unknown name evaluates as an empty value (so equals never matches while not_equals / is_none_of / not_contains always do). An unknown operator or document_type is not validated either and makes the request fail with HTTP 500.

Lifecycle

Publish and unpublish exist only in V1; V3 routes them but answers 404.

Enabling approval flows

• The feature is always on for companies created on or after 31 July 2025; older companies need it enabled for them (feature flag enable_approval_flow). When it is off every endpoint in this section answers 403 with {"error": ["Approval Flows feature is not enabled"], "status": 403}.
• Routing switches per document type, company-wide: as soon as one published, non-archived purchase_order flow exists, every PO in the company is routed by approval flows. The classic routing and its "please select approvers" check are bypassed, and a PO that matches no published flow is submitted as pending with no approvers at all. Make sure your published flows cover every PO (e.g. keep a catch-all flow) before you publish the first one. Unpublishing or archiving the last PO flow switches back.
• The same applies to invoices once a published invoice flow exists, with one safety net: when an invoice matches no custom invoice flow, the system creates (once) and uses a default invoice flow - is_default: true, named "Default Invoice Approval Flow", one step with the company's finance users (or admins) and the condition invoice_status equals outstanding. The default flow can be edited but not unpublished, archived or deleted.

How a flow is selected for a document

When a document is submitted, every published, non-archived flow of its type whose flow conditions all match is attached - several flows can run on the same document at once, and the document is approved only when all of them are complete. Each attachment is a run (approval_entity) with status in_progress, completed, rejected or cancelled; the flow keeps counters of its runs (in_progress_entities_count, ...). List them with GET /approval_flows/:id/runs. To preview which flow and approvers a draft PO would get, use POST /purchase_orders/approver_list (it can also test an unpublished flow with test_mode + approval_flow_id).

Editing a flow, versions and reruns

• Every save of a flow is recorded; version_no (a YYYYMMDDHHMMSS string) is stamped on each update. GET /approval_flows/:id/versions lists the earlier states and GET /approval_flows/:id/version_details returns one of them.
• Editing a flow does not re-route documents already in approval. If the edit changes the steps, approvers or conditions (not just the name or self_approval_allowed), every in-progress PO/invoice of the flow is flagged as "flow changed". POST /approval_flows/rerun_approval_flows then re-evaluates flagged documents in the background: runs that still match keep their approved requests and drop pending requests of approvers who are no longer in the active step; runs that no longer match are removed; newly matching published flows are attached; a comment is added to the PO history. Documents that were not flagged are left alone.
• A single invoice can also be rerun with POST /invoices/:id/rerun_approval_flow.

Permissions

Any other caller gets 401 {"error": "Unauthorized access", "status": 401} (also returned when publishing a flow that is already published, unpublishing one that is not, or deleting/archiving/unpublishing the default flow).

API versions

V1 and V3 share the request and response formats. V3 lacks publish, unpublish and export, does not hide runs of cancelled/archived POs, and its rerun_approval_flows accepts purchase orders only - see each endpoint.

Endpoints in this section

The approval flow object

List approval flows

curl "https://app.procurementexpress.com/api/v3/approval_flows?per_page=10" \
  -H "Authorization: Bearer $PEX_ACCESS_TOKEN" \
  -H "app_company_id: $PEX_COMPANY_ID"

curl "https://app.procurementexpress.com/api/v1/approval_flows?per_page=10" \
  -H "authentication_token: $PEX_AUTH_TOKEN" \
  -H "app_company_id: $PEX_COMPANY_ID"

require "rest-client"
require "json"

response = RestClient::Request.execute(
  method: :get,
  url: "https://app.procurementexpress.com/api/v3/approval_flows",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch('PEX_ACCESS_TOKEN')}",
    "app_company_id" => ENV.fetch("PEX_COMPANY_ID"),
    params: {
      per_page: "10"
    }
  }
)

puts JSON.pretty_generate(JSON.parse(response.body))

require "rest-client"
require "json"

response = RestClient::Request.execute(
  method: :get,
  url: "https://app.procurementexpress.com/api/v1/approval_flows",
  headers: {
    "authentication_token" => ENV.fetch("PEX_AUTH_TOKEN"),
    "app_company_id" => ENV.fetch("PEX_COMPANY_ID"),
    params: {
      per_page: "10"
    }
  }
)

puts JSON.pretty_generate(JSON.parse(response.body))

Response 200 OK, same structure in V3 and V1 (lists shortened to 2 items):

{
  "approval_flows": [
    {
      "id": 4,
      "name": "Large outstanding invoices",
      "document_type": "invoice",
      "self_approval_allowed": true,
      "company_id": 20000,
      "version_no": null,
      "archived": false,
      "status": "unpublished",
      "in_progress_entities_count": 0,
      "completed_entities_count": 0,
      "rejected_entities_count": 0,
      "cancelled_entities_count": 0,
      "total_entities_count": 0,
      "is_default": false,
      "created_at": 1792576869,
      "updated_at": 1792576869
    },
    {
      "id": 3,
      "name": "Large outstanding invoices",
      "document_type": "invoice",
      "self_approval_allowed": true,
      "company_id": 20000,
      "version_no": null,
      "archived": false,
      "status": "unpublished",
      "in_progress_entities_count": 0,
      "completed_entities_count": 0,
      "rejected_entities_count": 0,
      "cancelled_entities_count": 0,
      "total_entities_count": 0,
      "is_default": false,
      "created_at": 1792576869,
      "updated_at": 1792576869
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 4
  }
}

Example: search (V3, 200 OK):

{
  "approval_flows": [
    {
      "id": 1,
      "name": "Lab PO routing v1",
      "document_type": "purchase_order",
      "self_approval_allowed": false,
      "company_id": 20000,
      "version_no": null,
      "archived": false,
      "status": "unpublished",
      "in_progress_entities_count": 0,
      "completed_entities_count": 0,
      "rejected_entities_count": 0,
      "cancelled_entities_count": 0,
      "total_entities_count": 0,
      "is_default": false,
      "created_at": 1792576772,
      "updated_at": 1792576772
    },
    {
      "id": 2,
      "name": "Lab PO routing v3",
      "document_type": "purchase_order",
      "self_approval_allowed": false,
      "company_id": 20000,
      "version_no": null,
      "archived": false,
      "status": "unpublished",
      "in_progress_entities_count": 0,
      "completed_entities_count": 0,
      "rejected_entities_count": 0,
      "cancelled_entities_count": 0,
      "total_entities_count": 0,
      "is_default": false,
      "created_at": 1792576781,
      "updated_at": 1792576781
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 2
  }
}

V3 V1

Returns the company's non-archived approval flows, newest first, without their steps and conditions.

Lists all approval flows of every document type for the company in the app_company_id header. Archived and deleted flows are not included (an archived flow can still be fetched by id). Items are the flow summary only - fetch a flow by id to get its steps and conditions.

• search filters by name (case-insensitive substring).
• Sorting defaults to id descending. sort must be a table-qualified column, approval_flows.<column> (e.g. approval_flows.name, approval_flows.created_at, approval_flows.total_entities_count); anything else - including a bare name - silently falls back to id. The special value approval_flows.completed_entities_count+approval_flows.rejected_entities_count sorts by finished runs (URL-encode the + as %2B).
• Paginated with page / per_page.

HTTP request

Permissions

Company admin or finance role in the header company. Others: 401 Unauthorized access.

Query parameters

Response

200 with {"approval_flows": [...], "meta": {...}}. Each item is an approval flow summary (see the object table, without approval_steps / approval_conditions). meta holds current_page, next_page, prev_page, total_pages, total_count.

V3 and V1 differences

None - identical request and response.

Errors

Get an approval flow

curl "https://app.procurementexpress.com/api/v3/approval_flows/1" \
  -H "Authorization: Bearer $PEX_ACCESS_TOKEN" \
  -H "app_company_id: $PEX_COMPANY_ID"