Create Purchase Order

POST/purchase-orders

Agency-scoped keys

This endpoint is not available for agency-scoped API keys.

Summary

Requires write:purchase-orders. Creates an active purchase order for projects belonging to one company attached to the key. The company is inferred from the projects.

Set massLink to true to link matching existing assignments currently without a PO. Matching uses company, projects, agency, site and trade applicability, excludes cancelled assignments and assignments with an invoice, and does not replace an existing PO. A tag matching no trades links no assignments. The default is false.

Request Fields

Name	Type	Required	Description
reference	string	Yes	Unique trimmed reference within the company
projects	array	Yes	Project object ids in one accessible company
agency	string	Yes	Use agency.id from List Connected Agencies for the company; creation only
site	string	No	Site object id in the single selected project, or null for all sites; creation only
value	number	Yes	Non-negative finite value
startDate	string	Yes	ISO date or timestamp
endDate	string	Yes	ISO date or timestamp, on or after startDate
massLink	boolean	No	Link matching existing assignments without a PO or invoice, excluding cancelled assignments; creation only
tradeOption	string	No	all, specific or tag; defaults to all on creation
trades	array	For specific tradeOption	Use each trade’s id from List Trades, filtered by company; required and non-empty for specific tradeOption
tag	string	For tag tradeOption	Use the tag’s id from Get Company Tags with resourceType=trade; required for tag tradeOption

Related-resource identifiers must be object ids. Dates accept ISO date-only strings (midnight UTC) or timestamps with a timezone. Choose the end timestamp to cover the intended final day. Currency is always set to the company default and cannot be supplied in the request.

Request Example

cURL

curl -X POST 'https://api.requidex.com/api/open/v1/purchase-orders' \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "reference": "PO-44321",
  "projects": [
    "67bc36db80a1616ec3f47011"
  ],
  "agency": "67bc36db80a1616ec3f47060",
  "value": 150000,
  "startDate": "2026-01-01",
  "endDate": "2026-12-31T22:00:00Z",
  "massLink": false,
  "tradeOption": "all"
}'

JavaScript

const response = await fetch(
  "https://api.requidex.com/api/open/v1/purchase-orders",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer <API_KEY>",
      Accept: "application/json",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      reference: "PO-44321",
      projects: ["67bc36db80a1616ec3f47011"],
      agency: "67bc36db80a1616ec3f47060",
      value: 150000,
      startDate: "2026-01-01",
      endDate: "2026-12-31T22:00:00Z",
      massLink: false,
      tradeOption: "all",
    }),
  },
);

const json = await response.json();

Python

import requests

response = requests.post(
    'https://api.requidex.com/api/open/v1/purchase-orders',
    headers={
        'Authorization': 'Bearer <API_KEY>',
        'Accept': 'application/json',
    },
    json={'reference': 'PO-44321',
     'projects': ['67bc36db80a1616ec3f47011'],
     'agency': '67bc36db80a1616ec3f47060',
     'value': 150000,
     'startDate': '2026-01-01',
     'endDate': '2026-12-31T22:00:00Z',
     'massLink': False,
     'tradeOption': 'all'},
    timeout=30,
)

print(response.json())

Go

package main

import (
  "fmt"
  "io"
  "net/http"
  "strings"
)

func main() {
  body := strings.NewReader(`{
  "reference": "PO-44321",
  "projects": [
    "67bc36db80a1616ec3f47011"
  ],
  "agency": "67bc36db80a1616ec3f47060",
  "value": 150000,
  "startDate": "2026-01-01",
  "endDate": "2026-12-31T22:00:00Z",
  "massLink": false,
  "tradeOption": "all"
}`)
  req, err := http.NewRequest("POST", "https://api.requidex.com/api/open/v1/purchase-orders", body)
  if err != nil {
    panic(err)
  }
  req.Header.Set("Authorization", "Bearer <API_KEY>")
  req.Header.Set("Accept", "application/json")
  req.Header.Set("Content-Type", "application/json")

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()

  payload, err := io.ReadAll(resp.Body)
  if err != nil {
    panic(err)
  }
  fmt.Println(string(payload))
}

Response Fields

Field	Type	Description
agency	object	Show child attributes id string - Agency id name string - Agency name
allTrades	boolean	Whether the purchase order applies to all trades
company	object	Show child attributes id string - Company id name string - Company name
createdAt	string	Creation timestamp
endDate	string	Purchase order end date
id	string	Purchase order id
projects	array[object]	Show child attributes id string - Project id name string - Project name
reference	string	Purchase order reference
site	object	Show child attributes id string - Site id name string - Site name
startDate	string	Purchase order start date
status	string	Possible values: active, inactive (revoked), or expired; always active on creation
tag	object	Only included when a tag is set. Show child attributes id string - Tag id name string - Tag name
tradeOption	string	Trade selection mode
trades	array[object]	Show child attributes id string - Trade id name string - Trade name
updatedAt	string	Last update timestamp
value	number	Purchase order value

Response Example (200)

{
  "success": true,
  "data": {
    "id": "67bc36db80a1616ec3f48001",
    "status": "active",
    "reference": "PO-44321",
    "startDate": "2026-01-01T00:00:00.000Z",
    "endDate": "2026-12-31T22:00:00.000Z",
    "value": 150000,
    "company": {
      "id": "67bc36db80a1616ec3f47001",
      "name": "Requidex Construction Ltd"
    },
    "projects": [
      {
        "id": "67bc36db80a1616ec3f47011",
        "name": "Project Alpha"
      }
    ],
    "site": null,
    "agency": {
      "id": "67bc36db80a1616ec3f47060",
      "name": "Agency One"
    },
    "trades": [],
    "allTrades": true,
    "tradeOption": "all",
    "createdAt": "2026-01-10T12:00:00.000Z",
    "updatedAt": "2026-02-20T14:03:12.111Z"
  }
}

Errors

HTTP Status	Description
400	Invalid fields, no effective changes, or linked-assignment restrictions
401	Missing, invalid, revoked or expired API key
403	Missing scope or agency-scoped key
404	Purchase order or related resource not found in the accessible company
429	Rate limit exceeded
500	Unexpected internal error