Introduction

https://app.procurementexpress.com

https://app.procurementexpress.com

Welcome to V1 API documentaiton for ProcurementExpress - A simple Purchase Order solution.

We currently have language bindings in Shell and Ruby! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Authentication

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/api/v3/endpoint',
  headers={authentication_token: 'your token'}
)

# With shell, you can just pass the correct header with each request

curl "https://app.procurementexpress.com/api/v3/endpoint"
  -H "authentication_token: your token"

Authenticate your account when using the API by including your authentication_token in the Header Request.

Make sure your authenticated request are including: -H "authentication_token: your token"

Errors

ProcurementExpress uses conventional HTTP response codes to indicate the success or failure of an API request.

Error Code	Meaning	Description
400	Bad Request	The request was unacceptable
401	Unauthorized	No valid authentication token provided
403	Forbidden	The requested resource is hidden for admin only
404	Not Found	The specified resource could not be found
500, 502, 503, 504	Server Errors	Something went wrong on ProcurementExpress's end. (these are rare)

Internationalization

Country and Regional Support

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/api/v3/endpoint',
  headers = {
    locale: 'es'
  }
)

curl https://app.procurementexpress.com/api/v3/endpoint'
  -H "locale: es"

We support Country specific languages

Language	Key
English	en (default)
Spanish	es
Slovak	sk

We also support some regional languages

Language	Region	Key
Spanish	Chile	es-CL
Spanish	Maxican	es-MX

HTTP Request

POST https://app.procurementexpress.com/api/v3/endpoint

Query Parameters

Param	Type	Description
locale	header	locale key for required language support

Oauth2 Authentication for V3 Api

require 'rest-client'

RestClient.post(
  'https://app.procurementexpress.com/oauth/token',
  {
    client_id: 'client Iid',
    client_secret: "client secret",
    email: "[email protected]",
    password: 'password',
    grant_type: "grant_type",
  }
)

curl https://app.procurementexpress.com/oauth/token
  -X POST
  -d "client_id: client id"
  -d "client_secret: client secret"
  -d "[email protected]"
  -d "password=password"
  -d "grant_type=grant_type"

{
  "access_token": "NoR6Oz8OG5Ci....WXmC_8WE",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "NxmOamX....TqekmatIw",
  "scope": "public",
  "created_at": 1692767229
}

Use this API endpoint to get Oauth2 based access_token, that can be used to access any V3 API endpoints.

HTTP Request

POST https://app.procurementexpress.com/oauth/token

Query Parameters

Param	Type	Description
email	string	email
password	string	strong password
grant_type	string	password
client_id	string	client_id
client_secret	string	client_secret

Revoke a token (or Sign out)

require 'rest-client'

RestClient.post(
  'https://app.procurementexpress.com/oauth/revoke',
  headers: {
    'Authorization': 'Bearer <token>'
  },
  {
    client_id: 'client Iid',
    client_secret: "client secret"
  }
)

curl https://app.procurementexpress.com/oauth/token
  -X POST
  -H "Authorization: Bearer <token>"
  -d "client_id: client id"
  -d "client_secret: client secret"

HTTP Request

POST https://app.procurementexpress.com/oauth/revoke

HTTP Request

Authorization: Bearer <token>

Query Parameters

Param	Type	Description
client_id	String	client_id
client_secret	String	client_secret
Authorization	header	Bearer token header

Check if token is valid

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/oauth/token/info',
  headers: {
    'Authorization': 'Bearer <token>',
    app_company_id: 1
  }
)

curl https://app.procurementexpress.com/oauth/token/info
  -X GET
  -H "Authorization: Bearer <token>"
  -H "app_company_id: 1"

HTTP Request

GET https://app.procurementexpress.com/oauth/token/info

HTTP Request

Authorization: Bearer <token>

Accessing resources with bearer token

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/api/v3/budgets',
  headers: {
    "Authorization": 'Bearer <token>',
    app_company_id: 1
  }
)

curl https://app.procurementexpress.com/api/v3/budgets
  -X GET
  -H "Authorization: Bearer <token>"
  -H "app_company_id: 1"

HTTP Request

GET https://app.procurementexpress.com/api/v3/budgets

HTTP Request

Authorization: Bearer <token>

Users

GET Current User

require 'rest-client'

response = RestClient.get(
  'https://app.procurementexpress.com/api/v1/currentuser',
  headers = {
    authentication_token: 'your token',
    app_company_id: '1'
  }
)

response.body

curl 'https://app.procurementexpress.com/api/v1/currentuser'
  -X GET
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"

{
  "id": 1,
  "email": "[email protected]",
  "name": "Api user",
  "phone_number": "98xxxxxxxx",
  "setup_incomplete": false,
  "employer_id": 1,
  "authentication_token": "t0k3n",
  "approval_limit": 0,
  "companies": [
    {
      "id": 1,
      "name": "My Demo Company",
      "external_user_id": "7VMSFPvs7Cyj",
      "membership_archived": false,
      "is_locked": false,
      "is_removed": false,
      "approval_limit": 1000000,
      "in_trial": false,
      "trial_expired": true,
      "remaining_trial_days": -5,
      "roles": ["companyadmin", "approver", "finance", "teammember"]
    }
  ]
}

Retrieves the details of current logged in user. You need to supply the user's authentication token and company id as a header params.

Available Roles

Each user can have various roles for their different companies. List of available roles are: companyadmin, approver, finance, teammember.

Check if app_company_id is current employer id

To Check if the user's mobile company is the active employer among many companies, you can check current_user.employer_id === app_company_id where current_user is the current logged in user in mobile app with authentication_token and app_company_id is the active company for that user in that mobile.

About `external_user_id`

We can now see external_user_id for companies array in json response. The value of this field can be set from ProcurementExpress.com web application. This value is unique per companies that is 2 employee from same companies can't have duplicate external_user_id. Maximum characters supported in this field is 64 characters.

HTTP Request

GET https://app.procurementexpress.com/api/v1/currentuser

URL Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	registered company id

Update User

require 'rest-client'

RestClient.put(
  'https://app.procurementexpress.com/api/v1/currentuser',
  {
    email: '[email protected]',
    password: 'password',
    name: 'John Doe',
    phone_number: '98xxxxxxxx'
  },
  headers = { authentication_token: 'your token', }
)

curl https://app.procurementexpress.com/api/v1/currentuser
  -X PUT
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"
  -d "[email protected]"
  -d "password=password"
  -d "name=John Doe"
  -d "phone_number=98xxxxxxxx"

{
  "id": 1,
  "email": "[email protected]",
  "name": "John Doe",
  "phone_number": "98xxxxxxxx",
  "setup_incomplete": false,
  "employer_id": 1,
  "authentication_token": "newt0k3n",
  "approval_limit": 0,
  "companies": [
    {
      "id": 1,
      "name": "My Demo Company",
      "external_user_id": "7VMSFPvs7Cyj",
      "membership_archived": false,
      "is_locked": false,
      "is_removed": false,
      "approval_limit": 1000000,
      "in_trial": false,
      "roles": ["companyadmin", "approver", "finance", "teammember"]
    }
  ]
}

Update current logged in user setting the value of parameters passed. Any parameters not provided will be left unchanged.

HTTP Request

PUT https://app.procurementexpress.com/api/v1/currentuser

Query Parameters

Param	Type	Description
authentication_token	header	Authentication token
app_company_id	header	registered company id
email	string	email
password	string	strong password
name	string	Your First and Last name
phone_number	string	Phone number

Get My Currencies

require 'rest-client'

response = RestClient.get(
  'https://app.procurementexpress.com/api/v3/currencies',
  headers = {
    authentication_token: 'your token',
    app_company_id: '1'
  }
)

curl 'https://app.procurementexpress.com/api/v3/currencies'
  -X GET
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"

[
  {
    "id": 1,
    "iso_code": "EUR",
    "iso_numeric": "978",
    "name": "Euro",
    "symbol": "€"
  },
  {
    "id": 2,
    "iso_code": "GBP",
    "iso_numeric": "826",
    "name": "British Pound",
    "symbol": "£"
  },
  ...
]

Returns a list of currencies that are enabled for given company id.

HTTP Request

GET https://app.procurementexpress.com/api/v3/currencies

Query Parameters

Param	Type	Description
authentication_token	header	Authentication token
app_company_id	header	registered company id

Get All Currencies

require 'rest-client'

response = RestClient.get(
  'https://app.procurementexpress.com/api/v3/all_currencies',
  headers = {
    authentication_token: 'your token',
  }
)

curl 'https://app.procurementexpress.com/api/v3/all_currencies'
  -X GET
  -H "Content-Type: application/json"
  -H "authentication_token: your token"

[
  {
    "id": 8,
    "iso_code": "AFN",
    "iso_numeric": "971",
    "name": "Afghan Afghani",
    "symbol": "؋"
  },
  {
    "id": 9,
    "iso_code": "ALL",
    "iso_numeric": "008",
    "name": "Albanian Lek",
    "symbol": "L"
  },
  {
    "id": 45,
    "iso_code": "DZD",
    "iso_numeric": "012",
    "name": "Algerian Dinar",
    "symbol": "د.ج"
  },
  {
    "id": 12,
    "iso_code": "AOA",
    "iso_numeric": "973",
    "name": "Angolan Kwanza",
    "symbol": "Kz"
  },
  {
    "id": 13,
    "iso_code": "ARS",
    "iso_numeric": "032",
    "name": "Argentine Peso",
    "symbol": "$"
  },
  {
    "id": 10,
    "iso_code": "AMD",
    "iso_numeric": "051",
    "name": "Armenian Dram",
    "symbol": "դր."
  },
  {
    "id": 14,
    "iso_code": "AWG",
    "iso_numeric": "533",
    "name": "Aruban Florin",
    "symbol": "ƒ"
  },
  {
    "id": 5,
    "iso_code": "AUD",
    "iso_numeric": "036",
    "name": "Australian Dollar",
    "symbol": "$"
  },
  ...
]

Returns a list of all available currencies.

HTTP Request

GET https://app.procurementexpress.com/api/v3/all_currencies

Query Parameters

Param	Type	Description
authentication_token	header	Authentication token

Budgets

Create a Budget

require 'rest-client'

RestClient.post(
  'https://app.procurementexpress.com/api/v3/budgets',
  {
    budget: {
      amount: 100.0,
      name: 'Test',
      currency_id: 1,
      creator_id: 1,
      allow_anyone_to_approve_a_po: false,
      department_ids: [1,4],
      approver_ids: [1,2]
    }
  },
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl https://app.procurementexpress.com/api/v3/budgets
  -X POST
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"
  -d "budget[amount]=100.0"
  -d "budget[name]=Test"
  -d "budget[currency_id]=1"
  -d "budget[creator_id]=1"
  -d "budget[allow_anyone_to_approve_a_po]=false"
  -d "budget[department_ids]=[1,4]"
  -d "budget[approvers_ids]=[1,2]"

{
  "id": 1,
  "company_id": 1,
  "name": "Test",
  "amount": "100.0",
  "cost_code": null,
  "cost_type": null,
  "archived": false,
  "currency_id": 1,
  "base_amount": "100.0",
  "base_rate": "1.0",
  "allow_anyone_to_approve_a_po": false,
  "start_date": null,
  "end_date": null,
  "summary": "Test",
  "creator_id": 1,
  "department_ids": [],
  "approver_ids": []
}

Create a new Budget and returns the Budget object that is created.

Include associated departments and approvers

To add approvers to this you can pass approver_ids which expect array of approver ids in the POST request.

And to add departments you can pass department_ids which expect array of department ids in the POST request.

Date format should match `company_setting.date_format`

Because we support multiple date formats, we need to send dates depending on company_setting.date_format. In this API endpoint, you need to provide proper date format for start_date and end_date. Please find date format in Company Setting

HTTP Request

POST https://app.procurementexpress.com/api/v3/budgets

Query Parameters

Param	Type	Description
authentication_token	header	Authentication token
app_company_id	header	registered company id
budget[amount]	double	Budget Amount
budget[name]	string	Budget Name
budget[cost_code]	string	Budget cost code
budget[cost_type]	string	Budget cost type
budget[currency_id]	integer	Budget currency
budget[creator_id]	integer	Budget creator
budget[allow_anyone_to_approve_a_po]	boolean	Allow anyone to approve a PO?
budget[start_date]	date	Budget start date
budget[end_date]	date	Budget end date
budget[approver_ids]	Array	Array of approver ids
budget[department_ids]	Array	Array of department ids

GET All Budgets

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/api/v3/budgets',
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/budgets'
  -X GET
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"

{
  "budgets": [
    {
      "id": 1,
      "company_id": 1,
      "name": "Advocacy",
      "amount": "50000.0",
      "cost_code": "2017",
      "cost_type": null,
      "archived": false,
      "currency_id": 1,
      "base_amount": "50000.0",
      "base_rate": "1.0",
      "allow_anyone_to_approve_a_po": false,
      "start_date": 1483401600,
      "end_date": 1519862400,
      "summary": "Advocacy : 2017",
      "creator_id": 1,
      "department_ids": [],
      "approver_ids": []
    },
    {
      "id": 2,
      "company_id": 1,
      "name": "Audit And Accountancy Fees",
      "amount": "9000.0",
      "cost_code": "2017",
      "cost_type": null,
      "archived": false,
      "currency_id": 1,
      "base_amount": "9000.0",
      "base_rate": "1.0",
      "allow_anyone_to_approve_a_po": false,
      "start_date": 1483401600,
      "end_date": 1519862400,
      "summary": "Audit And Accountancy Fees : 2017",
      "creator_id": 1,
      "department_ids": [],
      "approver_ids": []
    },
    {
      "id": 3,
      "company_id": 1,
      "name": "Board Expenses",
      "amount": "100.0",
      "cost_code": "2017",
      "cost_type": null,
      "archived": false,
      "currency_id": 1,
      "base_amount": "100.0",
      "base_rate": "1.0",
      "allow_anyone_to_approve_a_po": false,
      "start_date": 1483401600,
      "end_date": 1519862400,
      "summary": "Board Expenses : 2017",
      "creator_id": 1,
      "department_ids": [],
      "approver_ids": []
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": 2,
    "prev_page": null,
    "total_pages": 3,
    "total_count": 50
  }

Returns a list of Budgets.

Filter budgets by department_id

you can pass department_id query params to filter budgets by departments like: /api/v3/budgets?department_id=1

Filter by archived

Return list of archived budgets by passing archived queryParams with value true. Example: /api/v3/budgets?archived=true. Default list are active budget lists.

Return budgets that are active till today

This filter will return list of active budgets based on budget.start_date and budget.end_date if your budget has periodic budget. This also includes all the budgets where both start_date and end_date are empty which are treated as non periodic budgets. Use /api/v3/budgets?only_active=true.

Pagination

Budget listing api results are paginated so that we don't load all budgets at once. You can send page params to load other records e.g: /api/v3/budgets?page=2. You can also see meta key in the response you get, that will return informations like current_page, next_page, previous_page, total_pages, and total_count to help your write your own logic for pagination.

HTTP Request

GET https://app.procurementexpress.com/api/v3/budgets?page=1&archived=false

Query Parameters

Param	Type	Description
authentication_token	header	Authentication token
app_company_id	header	registered company id
department_id	integer	Filter budgets by department

Get a specific Budget

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/api/v3/budgets/1',
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/budgets/1'
  -X GET
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"

{
  "id": 1,
  "company_id": 1,
  "name": "Advocacy",
  "amount": 50000.0,
  "cost_code": "2017",
  "cost_type": null,
  "archived": false,
  "currency_id": 1,
  "base_amount": 50000.0,
  "base_rate": "1.0",
  "allow_anyone_to_approve_a_po": false,
  "start_date": 1483401600,
  "end_date": 1519862400,
  "summary": "Advocacy : 2017",
  "remaining_amount": 50000.0,
  "creator_id": 1,
  "department_ids": [],
  "approver_ids": []
}

Retrieves the details of an existing budget. You need to supply the unique budget id that was returned upon budget creation.

HTTP Request

GET https://app.procurementexpress.com/api/v3/budgets/:id

URL Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	registered company id
ID	integer	The ID of the budget to retrieve

Update a Budget

require 'rest-client'

RestClient.put(
  'https://app.procurementexpress.com/api/v3/budgets/1',
  {
    budget: {
      amount: 200.0,
    }
  },
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/budgets/1'
  -X PUT
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"
  -d "budget[amount]=200.0"

{
  "id": 1,
  "company_id": 1,
  "name": "Test",
  "amount": "200.0",
  "cost_code": null,
  "cost_type": null,
  "archived": false,
  "currency_id": 1,
  "base_amount": "100.0",
  "base_rate": "1.0",
  "allow_anyone_to_approve_a_po": false,
  "start_date": null,
  "end_date": null,
  "summary": "Test",
  "creator_id": 1,
  "department_ids": [],
  "approver_ids": []
}

Update the specified Budget by setting the value of parameters passed. Any parameters not provided will be left unchanged.

HTTP Request

PUT https://app.procurementexpress.com/api/v3/budgets/:id

Query Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	registered company id
budget[amount]	double	Budget Amount
budget[name]	string	Budget Name
budget[cost_code]	string	Budget cost code
budget[cost_type]	string	Budget cost type
budget[currency_id]	integer	Budget currency
budget[creator_id]	integer	Budget creator
budget[allow_anyone_to_approve_a_po]	boolean	Allow anyone to approve a PO?
budget[start_date]	date	Budget start date
budget[end_date]	date	Budget end date
budget[approver_ids]	Array	Array of approver ids
budget[department_ids]	Array	Array of department ids

Comments

Add new comment for PO

require 'rest-client'

RestClient.post(
  'https://app.procurementexpress.com/api/v3/purchase_orders/1/comments',
  { comment: 'my first PO' },
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/purchase_orders/1/comments'
  -X POST
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"
  -d "comment=my first PO"

{
  "id": 1,
  "comment": "my first PO",
  "creator_id": 1,
  "creator_name": "John Doe",
  "purchase_order_id": 1,
  "status": "active",
  "created_at": 1505796377,
  "uploads": []
}

Create a new Comment for provided Purchase Order and returns the object that is created.

HTTP Request

POST https://app.procurementexpress.com/api/v3/purchase_order/:purchase_order_id/comments

Query Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Registered company id
purchase_order_id	integer	Purchase order id
comment	string	`Required` - Comment for purchase order

Companies

Create a company

require 'rest-client'

RestClient.post(
  'https://app.procurementexpress.com/api/v3/companies',
  {
    company: {
      name: 'ABC Corp.',
      gross_or_net_config: 1,
      company_setting_attributes: {
        currency_id: 1
      }
    }
  },
  headers = {
    authentication_token: 'your token'
  }
)

curl 'https://app.procurementexpress.com/api/v3/companies'
  -X POST
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -d "company[name]=ABC Corp."
  -d "company[gross_or_net_config]=1"
  -d "company[company_setting_attributes][currency_id]=1"

{
  "id": 1,
  "name": "ABC Corp."
}

Create a new Company and returns the Company object that is created.

HTTP Request

POST https://app.procurementexpress.com/api/v3/companies

Query Parameters

Params	Type	Description
authentication_token	header	Authentication token
company[name]	string	`Required` - Company name
company[gross_or_net_config]	integer	Gross or Net config
company[default_tax_rate]	double	Default TAX Rate
company[supported_currency_ids]	Array[]	Supported currency ids
company[company_currency_exchange_rates]	Array[]	Currency exchange rates
company[budget_attributes][0][amount]	double	Budget amount
company[budget_attributes][0][name]	string	Budget Name
company[budget_attributes][0][creator_id]	integer	Budget creator id
company[budget_attributes][0][currency_id]	integer	Budget currency id
company[company_setting_attributes][id]	integer	ID
company[company_setting_attributes][currency_id]	integer	`Required` - Company Setting's currency id
company[company_setting_attributes][pdf_font_size]	integer	PDF font size
company[company_setting_attributes][date_format]	string	Date format e.g: "%Y-%m-%d"
company[company_setting_attributes][custom_field_to_include_in_po_number_id]	integer	Custom field to include in PO number ID
company[company_setting_attributes][javascript]	string	Javascript setting
company[company_setting_attributes][departments_alias]	string	Department alias
company[company_setting_attributes][tax_label]	string	Tax label
company[company_setting_attributes][approvals_require_login]	boolean	Approvals require Login?
company[company_setting_attributes][show_po_item_number]	boolean	Show PO item number?
company[company_setting_attributes][fixed_supplier_list]	boolean	Fixed supplier List?
company[company_setting_attributes][display_remaining_budget_amount]	boolean	Display remaining budget amount?
company[company_setting_attributes][display_budget_on_pdf]	boolean	Display budget on PDF?
company[company_setting_attributes][fixed_product_list]	boolean	Fixed product list?
company[company_setting_attributes][show_tax_column]	boolean	Show TAX column?
company[company_setting_attributes][show_company_name]	boolean	Show company name?
company[company_setting_attributes][show_approver_name]	boolean	Show approver name?
company[company_setting_attributes][user_can_add_supplier]	boolean	User can add supplier?
company[company_setting_attributes][manually_approve_by_lowest_available_approvers]	boolean	Manually approve by lowest available approvers?
company[company_setting_attributes][share_po_access_by_department]	boolean	Share PO access by department?
company[company_setting_attributes][allow_budget_overruns]	boolean	Allow budget overruns?
company[company_setting_attributes][allocations_enabled]	boolean	Allocations enabled?
company[company_setting_attributes][pdf_background]	string	PDF background
company[company_setting_attributes][pdf_footer]	string	PDF footer
company[company_setting_attributes][logo]	string	Logo
company[company_setting_attributes][logo_alignment]	string	Logo alignment
company[company_setting_attributes][logo_content_type]	string	Logo content type
company[company_setting_attributes][budgets_alias]	string	Budget alias
company[company_setting_attributes][po_fields]	Array[]	PO fields

Get all companies

require 'rest-client'

response = RestClient.get(
  'https://app.procurementexpress.com/api/v3/companies',
  headers = {
    authentication_token: 'your token'
  }
)

response.body

curl 'https://app.procurementexpress.com/api/v3/companies'
  -X GET
  -H "Content-Type: application/json"
  -H "authentication_token: your token"

[
  {
    "id": 1,
    "name": "ABC Corp."
  },
  {
    "id": 2,
    "name": "Xyz Pvt. Ltd."
  }
]

Returns a list of companies for current logged in user.

HTTP Request

GET https://app.procurementexpress.com/api/v3/companies

Query Parameters

Params	Type	Description
authentication_token	header	Authentication token

Get a specific company

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/api/v3/companies/1',
  headers = {
    authentication_token: 'your token',
  }
)

curl 'https://app.procurementexpress.com/api/v3/companies/1'
  -X GET
  -H "Content-Type: application/json"
  -H "authentication_token: your token"

How to find active/required QuickBook's Class and customer fields?

Use company_setting.qbo_customer_required field to check if QuickBooks customer field is required field for purchase order or invoice creation
Use company_setting.qbo_customer_active field to check if QuickBooks customer field is visible in purchase order or invoice creation form. Also Note that you might need to forcefully display this field if qbo_customer_required field is true.
Use company_setting.qbo_class_required field to check if QuickBooks class field is required for purchase order or invoice creation
Use company_setting.qbo_class_active field to check if QuickBooks class field is required for purchase order or invoice creation form. Also Note that you might need to forcefully display this field if qbo_customer_required field is true.

{
  "id": 1,
  "name": "ABC Corp.",
  "employees_count": 10,
  "default_tax_rate": "13.0",
  "company_setting": {
    "id": 1,
    "show_po_item_number": false,
    "gross_or_net": "net",
    "company_id": 1,
    "fixed_supplier_list": true,
    "currency_id": 1,
    "javascript": "",
    "departments_alias": "",
    "display_remaining_budget_amount": true,
    "date_format": "%Y-%m-%d",
    "tax_label": "VAT",
    "approvals_require_login": false,
    "fixed_product_list": false,
    "show_tax_column": true,
    "show_company_name": true,
    "allow_budget_overruns": true,
    "budgets_alias": "",
    "allocations_enabled": false,
    "report_name": null,
    "user_can_add_supplier": true,
    "po_fields": ["Date", "Budgets", "From", "PO number", "Net Amount"],
    "reserve_po_number": false,
    "qbo_customer_required": true,
    "qbo_customer_active": true,
    "qbo_class_required": true,
    "qbo_class_active": true,
    "show_qbo_chart_of_account_number": true
  },
  "custom_fields": [
    {
      "id": 1,
      "company_id": 1,
      "name": "Reason for expenditure",
      "field_type": "select",
      "active": false,
      "required": false,
      "options": ["Acquisition of new donors.", "Existing donors."],
      "access_level": "everyone",
      "position": 0,
      "on_line_item": false,
      "display_on_pdf": false,
      "on_budget": false,
      "editable_after_approval": null
    },
    {
      "id": 2,
      "company_id": 1,
      "name": "Expenditure Breakdown",
      "field_type": "select",
      "active": true,
      "required": true,
      "options": [
        "Agency Fees",
        "Media Expenses",
        "Consultants",
        "Telephone",
        "Travel",
        "Other"
      ],
      "access_level": "everyone",
      "position": 1,
      "on_line_item": false,
      "display_on_pdf": false,
      "on_budget": false,
      "editable_after_approval": null
    }
  ],
  "supported_currencies": [
    {
      "id": 1,
      "iso_code": "EUR",
      "iso_numeric": "978",
      "name": "Euro",
      "symbol": "€"
    },
    {
      "id": 2,
      "iso_code": "GBP",
      "iso_numeric": "826",
      "name": "British Pound",
      "symbol": "£"
    },
    {
      "id": 3,
      "iso_code": "USD",
      "iso_numeric": "840",
      "name": "United States Dollar",
      "symbol": "$"
    },
    {
      "id": 5,
      "iso_code": "AUD",
      "iso_numeric": "036",
      "name": "Australian Dollar",
      "symbol": "$"
    }
  ]
}

Retrieves the details of an existing company. You need to send unique company id that was returned upon company creation.

HTTP Request

GET https://app.procurementexpress.com/api/v3/companies/:id

URL Parameters

Params	Type	Description
authentication_token	header	Authentication token
ID	integer	Company Id

Approvers

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/api/v3/companies/approvers?department_id=1',
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/companies/approvers?department_id=1'
  -X GET
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"

[
  {
    "id": 1,
    "email": "[email protected]",
    "name": "Admin User",
    "phone_number": "",
    "setup_incomplete": false,
    "employer_id": 1,
    "authentication_token": "token",
    "approval_limit": 1000000,
    "companies": [
      {
        "id": 1,
        "name": "ABC Corp."
      }
    ]
  },
  {
    "id": 2,
    "email": "[email protected]",
    "name": "Accountant User",
    "phone_number": "",
    "setup_incomplete": false,
    "employer_id": 2,
    "authentication_token": "token",
    "approval_limit": 1000000,
    "companies": [
      {
        "id": 1,
        "name": "ABC Corp."
      }
    ]
  }
]

Retrieves the list of approvers for current company. It will return [] if it is an auto approval PO.

Filter By Department

You can filter approvers list with department by passing department_id query params.

Filtered By `Allow approvers to approve their own request`

If Company setting -> Purchase Order -> Allow approvers to approve their own request setting is enabled then approvers are allowed to approve their own purchase order therefore you will see logged in approver in the list of approvers. But if the setting is off, then approvers are not allowed to approve their own purchase order so the approvers list does not contains logged in approver on the list. In below screenshot You can see the setting is enabled.

This setting is Off by default and approvers are not allowed to approve their own request.

allow_approvers_to_approve_their_own_request

HTTP Request

GET https://app.procurementexpress.com/api/v3/companies/approvers?department_id=:id

URL Parameters

Params	Type	Description
authentication_token	headers	Authentication token
app_company_id	headers	Company Id
department_id	integer	Optional, if you want to filter approvers by department

Get All Approvers

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/api/v3/companies/all_approvers',
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/companies/all_approvers'
  -X GET
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"

[
  {
    "id": 1,
    "email": "[email protected]",
    "name": "Admin User",
    "phone_number": "",
    "setup_incomplete": false,
    "employer_id": 1,
    "authentication_token": "token",
    "approval_limit": 1000000,
    "companies": [
      {
        "id": 1,
        "name": "ABC Corp."
      }
    ]
  },
  {
    "id": 2,
    "email": "[email protected]",
    "name": "Accountant User",
    "phone_number": "",
    "setup_incomplete": false,
    "employer_id": 2,
    "authentication_token": "token",
    "approval_limit": 1000000,
    "companies": [
      {
        "id": 1,
        "name": "ABC Corp."
      }
    ]
  }
]

Retrieves the list of all approvers for current company regardless of auto approval routing

HTTP Request

GET https://app.procurementexpress.com/api/v3/companies/all_approvers

URL Parameters

Params	Type	Description
authentication_token	headers	Authentication token
app_company_id	headers	Company Id

Get All Employees

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/api/v3/companies/employees',
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/companies/employees'
  -X GET
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"

[
  {
    "id": 1,
    "email": "[email protected]",
    "name": "Admin User",
    "phone_number": "",
    "setup_incomplete": false,
    "employer_id": 1,
    "approval_limit": 1000000,
    "companies": [
      {
        "id": 1,
        "approval_limit": 1000000
      }
    ],
    "roles": ["companyadmin", "finance", "approver", "teammember"]
  },
  {
    "id": 2,
    "email": "[email protected]",
    "name": "Accountant User",
    "phone_number": "",
    "setup_incomplete": false,
    "employer_id": 1,
    "approval_limit": 1000000,
    "companies": [
      {
        "id": 1,
        "approval_limit": 1000000
      }
    ],
    "roles": ["finance", "approver", "teammember"]
  }
]

Retrieves the list of all employees for current company.

HTTP Request

GET https://app.procurementexpress.com/api/v3/companies/employees

URL Parameters

Params	Type	Description
authentication_token	headers	Authentication token
app_company_id	headers	Company Id

Invite User

require 'rest-client'

RestClient.post(
  'https://app.procurementexpress.com/api/v3/companies/send_user_invite',
  {
    invite_user: {
      email: '[email protected]',
      name: 'Pherrel Williams',
      roles: ["approver", "teammember"]
    }
  },
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/companies/send_user_invite'
  -X POST
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"
  -d "invite_user[email][email protected]"
  -d "invite_user[name]=Pherrel Williams"
  -d "invite_user[roles]=approver"
  -d "invite_user[roles]=teammember"

{ "status": true }

Send invitation to the user.

HTTP Request

POST https://app.procurementexpress.com/api/v3/companies/send_user_invite

URL Parameters

Params	Type	Description
authentication_token	headers	Authentication token
app_company_id	headers	Company id
invite_user[email]	string	Email to send invitation to
invite_user[name]	string	User's first name and last name
invite_user[roles]	Array[]	List of Roles for that user. Available roles are: - companyadmin - approver - finance - teammember

Departments

Create a Department

require 'rest-client'

RestClient.post(
  'https://app.procurementexpress.com/api/v3/departments',
  {
    department: {
      name: 'Accounting',
      archived: false,
      contact_person: 'John doe',
      phone_number: '98xxxxxxxx',
      email: '[email protected]',
      address: '2156 Bruce Street',
      tax_number: '123456',
      budget_ids: [1,2],
      user_ids: [1]
    }
  },
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/departments'
  -X POST
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"
  -d "department[name]=Accounting"
  -d "department[archived]=false"
  -d "department[contact_person]=John doe"
  -d "department[phone_number]=98xxxxxxxx"
  -d "department[email][email protected]"
  -d "department[address]=2156 Bruce Street"
  -d "department[tax_number]=123456"
  -d "department[budget_ids][]=1"
  -d "department[budget_ids][]=2"
  -d "department[user_ids][]=1"

{
  "id": 1,
  "name": "Accounting",
  "company_id": 1,
  "archived": false,
  "contact_person": "John Doe",
  "tax_number": "123456",
  "phone_number": "98xxxxxxxx",
  "address": "2156 Bruce Street",
  "email": "[email protected]"
}

Create a new Department and returns the Department object that is created.

HTTP Request

POST https://app.procurementexpress.com/api/v3/departments

Query Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Company ID
department[name]	string	`Required` Department name
department[archived]	boolean	Archived?
department[contact_person]	string	Contact person
department[phone_number]	string	Phone number
department[email]	string	Valid email address
department[address]	string	Contact person's address
department[tax_number]	string	TAX number
department[budget_ids]	Array[]	Budget IDs
department[user_ids]	Array[]	User IDs

Get All Departments

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/api/v3/departments',
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/departments'
  -X GET
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"

[
  {
    "id": 1,
    "name": "Accounting",
    "company_id": 1,
    "archived": false,
    "contact_person": "John Doe",
    "tax_number": "123456",
    "phone_number": "98xxxxxxxx",
    "address": "2156 Bruce Street",
    "email": "[email protected]"
  },
  {
    "id": 2,
    "name": "HR",
    "company_id": 1,
    "archived": true,
    "contact_person": "Bruce Jordan",
    "tax_number": "1122",
    "phone_number": "",
    "address": "1122 Jordan Street",
    "email": "[email protected]"
  }
]

Returns a list of your departments.

Filter by archived

You can also filter only archived departments by sending archived params and set it's value to true or false as your requirements. example, /api/v3/departments?archived=true

Filter company specific departments

By default all departments associated with current logged in users are returned in the api response. If you want to list all department for given company then you can pass company_specific=true flag in the query params, example: /api/v3/departments?company_specific=true&archived=false

HTTP Request

GET https://app.procurementexpress.com/api/v3/departments

Query Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Registered company id
archived	boolean	Filter departments by archived
company_specific	boolean	Filter company specific department

Get a specific Department

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/api/v3/departments/1',
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/departments/1'
  -X GET
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"

  {
    "id": 1,
    "name": "Accounting",
    "company_id": 1,
    "archived": false,
    "contact_person": "John Doe",
    "tax_number": "123456",
    "phone_number": "98xxxxxxxx",
    "address": "2156 Bruce Street",
    "email": "[email protected]"
  }

Retrieves the details of an existing department. You need to supply the unique department id, that was returned upon department creation.

HTTP Request

GET https://app.procurementexpress.com/api/v3/departments/:id

URL Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Company ID
ID	integer	Department ID

Update a department

require 'rest-client'

RestClient.put(
  'https://app.procurementexpress.com/api/v3/departments/1',
  {
    department: {
      name: 'Accounting department',
    }
  },
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/departments/1'
  -X PUT
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"
  -d "department[name]=Accounting department"

{
  "id": 1,
  "name": "Accounting department",
  "company_id": 1,
  "archived": false,
  "contact_person": "John Doe",
  "tax_number": "123456",
  "phone_number": "98xxxxxxxx",
  "address": "2156 Bruce Street",
  "email": "[email protected]"
}

Update the specified department by setting the value of parameters passed. Any parameters not provided will be left unchanged.

HTTP Request

PUT https://app.procurementexpress.com/api/v3/departments/:id

Query Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Company ID
ID	integer	Department ID
department[name]	string	`Required` Department name
department[archived]	boolean	Archived?
department[contact_person]	string	Contact person
department[phone_number]	string	Phone number
department[email]	string	Valid email address
department[address]	string	Contact person's address
department[tax_number]	string	TAX number
department[budget_ids]	Array[]	Budget IDs
department[user_ids]	Array[]	User IDs

Products

Create a Product

require 'rest-client'

RestClient.post(
  'https://app.procurementexpress.com/api/v3/products',
  {
    product: {
      description: '1 IPad Charging Station',
      sku: 'SKU-001',
      unit_price: 44.23,
      supplier_id: 1
    }
  },
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/products'
  -X POST
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"
  -d "product[description]=1 IPad Charging Station"
  -d "product[sku]=SKU-001"
  -d "product[unit_price]=44.23"
  -d "product[supplier_id]=1"

{
  "id": 1,
  "supplier_id": 1,
  "sku": "SKU-001",
  "description": "1 IPad Charging Station",
  "unit_price": "44.23",
  "currency_id": null,
  "archived": false
}

Create a new products and returns the Product object that is created.

HTTP Request

POST https://app.procurementexpress.com/api/v3/products

Query Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Company ID
product[description]	string	`Required` Product Description
product[sku]	string	Product Stock Keeping Unit (sku)
product[unit_price]	decimal	Product Unit Price
product[supplier_id]	integer	Supplier ID

Get all Products

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/api/v3/products',
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/products'
  -X GET
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"

[
  {
    "id": 1,
    "supplier_id": 1,
    "sku": "SKU-001",
    "description": "1 IPad Charging Station",
    "unit_price": "44.23",
    "currency_id": null,
    "archived": false
  },
  {
    "id": 2,
    "supplier_id": 1,
    "sku": "SKU-002",
    "description": "Macbook Air Retina",
    "unit_price": "1300",
    "currency_id": null,
    "archived": false
  }
]

Returns a list of your products.

Filter products by supplier

you can pass supplier_id query params to filter products by supplier like: /api/v3/products?supplier_id=1

Filter archived products

If you want to filter archived products you can pass archived params like: /api/v3/products?archived=true

HTTP Request

GET https://app.procurementexpress.com/api/v3/products

Query Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Company ID
supplier_id	integer	filter by supplier
archived	boolean	filter archived products

Get Product details

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/api/v3/products/1',
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/products/1'
  -X GET
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"

{
  "id": 1,
  "supplier_id": 1,
  "sku": "SKU-001",
  "description": "1 IPad Charging Station",
  "unit_price": "44.23",
  "currency_id": null,
  "archived": false
}

Retrieves the details of an existing products. You need to supply the unique product id, that was returned upon product creation.

HTTP Request

GET https://app.procurementexpress.com/api/v3/products/:id

URL Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Company ID
ID	integer	Product ID

Update Product

require 'rest-client'

RestClient.put(
  'https://app.procurementexpress.com/api/v3/products/1',
  {
    product: {
      description: 'updated'
    }
  },
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/products/1'
  -X PUT
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"
  -d "product[description]=updated"

{
  "id": 1,
  "supplier_id": 1,
  "sku": "SKU-001",
  "description": "updated",
  "unit_price": "44.23",
  "currency_id": null,
  "archived": false
}

Update the specified department by setting the value of parameters passed. Any parameters not provided will be left unchanged.

HTTP Request

PUT https://app.procurementexpress.com/api/v3/products/:id

Query Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Company ID
ID	integer	Product ID
product[description]	string	`Required` Product Description
product[sku]	string	Product Stock Keeping Unit (sku)
product[unit_price]	decimal	Product Unit Price
product[supplier_id]	integer	Supplier ID

Purchase Orders

Create a Purchase Order

require 'rest-client'

RestClient.post(
  'https://app.procurementexpress.com/api/v3/purchase_orders',
  {
    commit: "Send",
    purchase_order: {
      creator_id: 1,
      status: "draft",
      supplier_id: 1,
      supplier_name: "John Doe",
      notes: "Notes",
      company_id: 1,
      currency_id: 1,
      department_id:  1,
      purchase_order_items_attributes: [
        {
          item_number: 'SKU-001',
          description: "hello",
          budget_id: 1,
          tax_rate_id: 1,
          status: "pending",
          quantity: "1.0",
          unit_price: "50"
        }
      ]
    }
  },
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/purchase_orders'
  -X POST
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"
  -d "commit=Send"
  -d "purchase_order[creator_id]=1"
  -d "purchase_order[status]=draft"
  -d "purchase_order[supplier_id]=1"
  -d "purchase_order[supplier_name]=John Doe"
  -d "purchase_order[notes]=Notes"
  -d "purchase_order[company_id]=1"
  -d "purchase_order[currency_id]=1"
  -d "purchase_order[department_id]=1"
  -d "purchase_order[purchase_order_items_attributes][][item_number]=sku-001"
  -d "purchase_order[purchase_order_items_attributes][][description]=hello"
  -d "purchase_order[purchase_order_items_attributes][][budget_id]=1"
  -d "purchase_order[purchase_order_items_attributes][][tax_rate_id]=1"
  -d "purchase_order[purchase_order_items_attributes][][status]=pending"
  -d "purchase_order[purchase_order_items_attributes][][quantity]=1.0"
  -d "purchase_order[purchase_order_items_attributes][][unit_price]=50"

{
  "id": 1,
  "company_id": 1,
  "approval_key": null,
  "department_id": 1,
  "department_name": "400852",
  "supplier_id": 1,
  "supplier_name": "John Doe",
  "status": "pending",
  "creator_id": 1,
  "currency_id": 1,
  "creator_name": "Robert W.",
  "amount": "50.55",
  "created_at": 1505972258,
  "updated_at": 1505972258,
  "notes": "Notes",
  "total_net_amount": "50.0",
  "total_gross_amount": "50.55",
  "base_gross_amount": "44.564375",
  "delivery_status": "not_delivered",
  "delivered_on": null,
  "custom_fields": null,
  "share_key": "HEFYPNLBYFMKROPXUTCMPGMQCOGROKOS20170921003738",
  "archived": false,
  "conversion_rate": "0.88159",
  "keywords": "John Doe James Kennedy  pending 44.56  1100044 - Embajadores de marca Google en Retail Chromecast hello 50.55 50.0",
  "self_approved": false,
  "xero_id": null,
  "synced_with_xero": false,
  "purchase_order_items": [
    {
      "id": 1,
      "description": "hello",
      "purchase_order_id": 1,
      "budget_id": 1,
      "budget_summary": "1100044 - Embajadores de marca Google en Retail Chromecast : F 9575 : TELEFONIA Y CELULARES",
      "gross_amount": "50.55",
      "vat": "1.1",
      "tax_rate_id": 1,
      "net_amount": "50.0",
      "status": "pending",
      "quantity": "1.0",
      "unit_price": "50.0",
      "item_number": "sku-001",
      "base_net_amount": "44.0795",
      "base_gross_amount": "44.564375",
      "gross_usd_amount": "50.55",
      "product_id": null,
      "received_quantity": null,
      "custom_field_values": []
    }
  ],
  "budgets": [
    {
      "id": 1,
      "company_id": 1,
      "name": "1100044 - Embajadores de marca Google en Retail Chromecast",
      "amount": "19500.0",
      "cost_code": "F 9575",
      "cost_type": "TELEFONIA Y CELULARES",
      "archived": false,
      "currency_id": 100,
      "base_amount": "19500.0",
      "base_rate": "1.0",
      "allow_anyone_to_approve_a_po": false,
      "start_date": null,
      "end_date": null,
      "summary": "1100044 - Embajadores de marca Google en Retail Chromecast : F 9575 : TELEFONIA Y CELULARES"
    }
  ],
  "tax_rates": [
    {
      "id": 71720,
      "name": "GST",
      "value": 5.0,
      "tax_amount": 0.5
    },
    {
      "id": 71721,
      "name": "QST QC",
      "value": 9.975,
      "tax_amount": 1.0
    }
  ],
  "purchase_order_comments": [],
  "custom_field_values": [],
  "payments": [],
  "purchase_order_item_payments": [],
  "uploads": [],
  "approver_requests": [
    {
      "id": 1,
      "status": "pending",
      "approver_name": "Gillian Neary",
      "approver_id": 2
    }
  ]
}

Create a new Purchase Order and return the Purchase Order object that is created. You need to pass commit param which accepts 2 values for now Draft and Send, these values will determine the status of the Purchase Order.

HTTP Request

POST https://app.procurementexpress.com/api/v3/purchase_orders

Query Parameters

Params	Type	Options	Description
authentication_token	header		Authentication Token
app_company_id	header		Company ID
commit	string	`Send` `Draft`	Possible values are `Send` and `Draft`
purchase_order[supplier_name]	string		Supplier Name
purchase_order[new_supplier_name]	string		New Supplier Name
purchase_order[department_id]	integer		Department ID
purchase_order[creator_id]	integer		Creator ID
purchase_order[supplier_id]	integer		Supplier ID
purchase_order[currency_id]	integer		Currency ID
purchase_order[notes]	string		Notes for this PO
purchase_order[status]	boolean	`Pending` `Draft`	Status
purchase_order[company_id]	integer		Company ID
purchase_order[approver_list]	Array[]		Approver list IDs
purchase_order[purchase_order_items_attributes][][id]	integer		Purchase order item id
purchase_order[purchase_order_items_attributes][][sequence_no]	integer		Sequence number
purchase_order[purchase_order_items_attributes][][description]	string		Description
purchase_order[purchase_order_items_attributes][][quantity]	decimal		Item quantity
purchase_order[purchase_order_items_attributes][][net_amount]	decimal		Net amount
purchase_order[purchase_order_items_attributes][][unit_price]	decimal		Unit price
purchase_order[purchase_order_items_attributes][][budget_id]	integer		Budget ID
purchase_order[purchase_order_items_attributes][][vat]	decimal		VAT
purchase_order[purchase_order_items_attributes][][item_number]	string		Item Number / SKU
purchase_order[purchase_order_items_attributes][][purchase_order_id]	integer		Purchase Order ID
purchase_order[purchase_order_items_attributes][][_destroy]	boolean	`true` `false`	set `true` if you want to delete specific row of item
purchase_order[purchase_order_items_attributes][custom_field_values_attributes][][id]	integer		`CustomFieldValue` ID
purchase_order[purchase_order_items_attributes][custom_field_values_attributes][][value]	string		Value for CustomFieldValue
purchase_order[purchase_order_items_attributes][custom_field_values_attributes][][custom_field_id]	integer		CustomField ID
purchase_order[custom_field_values_attributes][][id]	integer		CustomFieldValue ID
purchase_order[custom_field_values_attributes][][value]	string		Value for CustomFieldValue
purchase_order[custom_field_values_attributes][][custom_field_id]	integer		CustomField ID
purchase_order[purchase_order_comments_attributes][][id]	integer		PurchaseOrderComment ID
purchase_order[purchase_order_comments_attributes][][creator_id]	integer		Creator ID
purchase_order[purchase_order_comments_attributes][][comment]	integer		Comment
purchase_order[purchase_order_comments_attributes][][purchase_order_id]	integer		Purchase Order ID
purchase_order[purchase_order_comments_attributes][uploads_attributes][][id]	integer		Upload ID
purchase_order[purchase_order_comments_attributes][uploads_attributes][][file]	integer		file field used to upload file e.g: Images, Documents, etc
purchase_order[purchase_order_comments_attributes][uploads_attributes][][creator_id]	integer		Creator ID
purchase_order[purchase_order_comments_attributes][uploads_attributes][][_destroy]	boolean	`true` `false`	Set `true` if you want to delete specific row of upload
purchase_order[uploads_attributes][][id]	integer		Upload ID
purchase_order[uploads_attributes][][file]	integer		file field used to upload file e.g: Images, Documents, etc
purchase_order[uploads_attributes][][creator_id]	integer		Creator ID
purchase_order[uploads_attributes][][_destroy]	boolean	`true` `false`	Set `true` if you want to delete specific row of upload
purchase_order[requests_attributes][][id]	integer		Request ID
purchase_order[requests_attributes][][approver_id]	integer		Approver ID
purchase_order[requests_attributes][][_destroy]	boolean	`true` `false`	Set `true` if you want to delete specific row of request
purchase_order[allocations_attributes][][id]	integer		Allocation ID
purchase_order[allocations_attributes][][allocation_target_id]	integer		Allocation Target ID
purchase_order[allocations_attributes][][group_id]	integer		Group ID
purchase_order[allocations_attributes][][maybe_value]	integer		Value
purchase_order[allocations_attributes][][_destroy]	destroy	`true` `false`	set `true` if you want to delete specifi row of allocation

Get all Purchase Orders

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/api/v3/purchase_orders',
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/purchase_orders'
  -X GET
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"

{
  "purchase_orders": [
    {
      "id": 1,
      "approval_key": "100001-2023-01-01",
      "creator_name": "Bottom Man",
      "amount": "50.55",
      "status": "pending",
      "supplier_name": "Doggie Treats Ltd.",
      "keywords": "John doe James Kennedy  pending 44.56  1100044 - Embajadores de marca Google en Retail Chromecast hello 50.55 50.0",
      "created_at": 1505972258000,
      "currency_id": 1,
      "currency_symbol": "$",
      "currency_iso_code": "USD",
      "total_gross_amount": "50.55",
      "total_net_amount": "40.44",
      "base_gross_amount": 28.640227,
      "submitted_on": 1505972258000,
      "share_key": "YOURSHAREKEY123456789",
      "department_id": 35113,
      "department_name": "Home Office",
      "approver_requests": [
        {
          "id": 1,
          "status": "approved",
          "approver_name": "Middle Man",
          "approver_id": 2,
          "accept_token": "APPROVALACCEPTTOKEN",
          "reject_token": "APPROVALREJECTTOKEN",
          "delegate_id": null
        }
      ]
    },
    {
      "id": 2,
      "approval_key": "100002-2023-01-01",
      "creator_name": "Bottom Man",
      "amount": "101.10",
      "status": "pending",
      "supplier_name": "Doggie Treats Ltd.",
      "keywords": "John doe James Kennedy  pending 44.56  1100044 - Embajadores de marca Google en Retail Chromecast hello 50.55 50.0",
      "created_at": 1505972258000,
      "currency_id": 1,
      "currency_symbol": "$",
      "currency_iso_code": "USD",
      "total_gross_amount": "101.10",
      "total_net_amount": "80.88",
      "base_gross_amount": 57.280453,
      "submitted_on": 1505972258000,
      "share_key": "YOURSHAREKEY123456789",
      "department_id": 1,
      "department_name": "Home Office",
      "approver_requests": [
        {
          "id": 2,
          "status": "cancelled",
          "approver_name": "Middle Man",
          "approver_id": 2,
          "accept_token": "APPROVALACCEPTTOKEN",
          "reject_token": "APPROVALREJECTTOKEN",
          "delegate_id": null
        }
      ]
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": 2,
    "prev_page": null,
    "total_pages": 3,
    "total_count": 25
  }
}

Returns a list of purchase orders. The response of purchase orders are paginated, so it will only return first 20 records as a response.

Pagination

You can send orders_page params to load other records e.g: /api/v3/purchase_orders?orders_page=2. You can also see meta key in the response you get, that will return informations like current_page, next_page, previous_page, total_pages, and total_count to help your write your own logic of pagination.

Search

You can also search for your Purchase Order using search params example /api/v3/purchase_orders?search=your search keyword. It will perform full-text search and return result accordingly.

HTTP Request

GET https://app.procurementexpress.com/api/v3/purchase_orders?orders_page=1&search=something

Query Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Company ID
orders_page	integer	Used for Loading records from specified page number
search	string	Used for searching Purchase Order by search keyword

Get Purchase Order details

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/api/v3/purchase_orders/1',
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/purchase_orders/1'
  -X GET
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"

{
  "id": 284588,
  "company_id": 3,
  "approval_key": null,
  "department_id": 2996,
  "department_name": "400852",
  "supplier_id": 310511,
  "supplier_name": "deepak",
  "status": "pending",
  "currency_id": 3,
  "creator_id": 1,
  "creator_name": "James Kennedy",
  "creator_email": "[email protected]",
  "amount": "50.55",
  "created_at": 1505972258,
  "updated_at": 1505972258,
  "notes": "Notes",
  "total_net_amount": "50.0",
  "total_gross_amount": "50.55",
  "base_gross_amount": "44.564375",
  "delivery_status": "not_delivered",
  "delivered_on": null,
  "custom_fields": null,
  "share_key": "HEFYPNLBYFMKROPXUTCMPGMQCOGROKOS20170921003738",
  "archived": false,
  "conversion_rate": "0.88159",
  "keywords":
    "deepak James Kennedy  pending 44.56  1100044 - Embajadores de marca Google en Retail Chromecast hello 50.55 50.0",
  "self_approved": false,
  "xero_id": null,
  "synced_with_xero": false,
  "can_cancel": true,
  "can_archive": false,
  "can_receive_item": true,
  "can_cancel_receiving_items": false,
  "can_mark_as_paid": true,
  "purchase_order_items": [
    {
      "id": 507638,
      "description": "hello",
      "purchase_order_id": 284588,
      "budget_id": 40228,
      "budget_summary":
        "1100044 - Embajadores de marca Google en Retail Chromecast : F 9575 : TELEFONIA Y CELULARES",
      "gross_amount": "50.55",
      "vat": "1.1",
      "net_amount": "50.0",
      "status": "pending",
      "quantity": "1.0",
      "unit_price": "50.0",
      "item_number": null,
      "base_net_amount": "44.0795",
      "base_gross_amount": "44.564375",
      "gross_usd_amount": "50.55",
      "product_id": null,
      "received_quantity": 0.0,
      "custom_field_values": []
    }
  ],
  "budgets": [
    {
      "id": 40228,
      "company_id": 1591,
      "name": "1100044 - Embajadores de marca Google en Retail Chromecast",
      "amount": "19500.0",
      "cost_code": "F 9575",
      "cost_type": "TELEFONIA Y CELULARES",
      "archived": false,
      "currency_id": 100,
      "base_amount": "19500.0",
      "base_rate": "1.0",
      "allow_anyone_to_approve_a_po": false,
      "start_date": null,
      "end_date": null,
      "summary":
        "1100044 - Embajadores de marca Google en Retail Chromecast : F 9575 : TELEFONIA Y CELULARES"
    }
  ],
  "tax_rates": [
    {
      "id": 71720,
      "name": "GST",
      "value": 5.0,
      "tax_amount": 0.5
    },
    {
      "id": 71721,
      "name": "QST QC",
      "value": 9.975,
      "tax_amount": 1.0
    }
  ],
  "purchase_order_comments": [],
  "custom_field_values": [],
  "payments": [],
  "purchase_order_item_payments": [],
  "uploads": [],
  "approver_requests": [
    {
      "id": 1,
      "status": "pending",
      "approver_name": "Gillian Neary",
      "approver_id": 2,
      "accept_token": "17943-344853-20171017053411......",
      "reject_token": "17943-344853-20171017053411......"
    }
  ],
  "supplier": {
    "id": 1,
    "email": "[email protected]",
    ...
  }
}

Retrieves the details of an existing purchase orders. you need to supply the unique purchase order id, that was returned upon product creation.

PurchaseOrder's status will be approved if all of the approvers have already approved this purchase order. You can find list of approvers in approver_requests attribute.

Tax rates

You will also get TaxRates object which is the combination of all Single tax rates used in your purchase order, and the tax amounts are calculated for each tax rates by aggregating all the line items's net_amount for given tax rate.

HTTP Request

GET https://app.procurementexpress.com/api/v3/purchase_orders/:id

URL Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Company ID
ID	integer	Purchase Order ID

Pending Requests

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/api/v3/purchase_orders?requests=true',
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/purchase_orders?requests=true'
  -X GET
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"

{
  "purchase_orders": [
    {
      "id": 1,
      "creator_name": "James Kennedy",
      "amount": "50.55",
      "status": "pending",
      "supplier_name": "John Doe",
      "keywords": "John doe James Kennedy  pending 44.56  1100044 - Embajadores de marca Google en Retail Chromecast hello 50.55 50.0",
      "created_at": 1505972258000,
      "currency_id": 1,
      "currency_symbol": "$",
      "total_gross_amount": "50.55",
      "total_net_amount": "50.0",
      "base_gross_amount": "44.564375"
    },
    {
      "id": 2,
      "creator_name": "James Kennedy",
      "amount": "50.55",
      "status": "pending",
      "supplier_name": "John Doe",
      "keywords": "John Doe James Kennedy  pending 44.56  1100044 - Embajadores de marca Google en Retail Chromecast hello 50.55 50.0",
      "created_at": 1505972227000,
      "currency_id": 1,
      "currency_symbol": "$",
      "total_gross_amount": "50.55",
      "total_net_amount": "50.0",
      "base_gross_amount": "44.564375"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": 2,
    "prev_page": null,
    "total_pages": 3,
    "total_count": 25
  }
}

Retrieves the list of Pending requests in Chronological Order for current authentication_token.

Sorting

You can sort requests by column with asc and desc directions. Example if you want to sort requests in asc order by created_at column then: GET https://app.procurementexpress.com/api/v3/purchase_orders?requests=true&sort=created_at&direction=asc

Pagination

You can send page params to load paginated records e.g: /api/v3/purchase_orders?page=2. You can also see meta key in the response you get, that will return informations like current_page, next_page, previous_page, total_pages, and total_count to help your write your own logic of pagination.

Search

You can also search for your pending requests using search params example /api/v3/purchase_orders?search=your search keyword. It will perform full-text search and return matching results.

HTTP Request

GET https://app.procurementexpress.com/api/v3/purchase_orders?requests=true

URL Parameters

params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Company ID
sort	string	sorting column name
direction	string	sorting direction. values are: - `asc` - `desc`
page	integer	page number

Pending Requests Count

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/api/v3/purchase_orders/pending_request_count',
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/purchase_orders/pending_request_count'
  -X GET
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"

{
  "total_pending_request": 2
}

Count total number of pending requests for current authentication_token.

HTTP Request

GET https://app.procurementexpress.com/api/v3/purchase_orders/pending_request_count

URL Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Company ID

Approve

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/api/v3/purchase_orders/1/approve',
  {
    token: 'accept-token'
  },
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/purchase_orders/1/approve'
  -X GET
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"
  -d "token=accept-token"

{
  "status": true
}

Approve purchase order. You must pass valid accept token to approve the Purchase order.

HTTP Request

GET https://app.procurementexpress.com/api/v3/purchase_orders/:id/approve

URL Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Company ID
token	string	Approver's accept token

Approval Override

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/api/v3/purchase_orders/1/override_and_approve',
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/purchase_orders/1/override_and_approve'
  -X GET
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"

{
  "status": true
}

Approve a Purchase Order via 'Approval Override' functionality. This endpoint is only availble to Finance users. This endpoint differs from 'Approval' in the fact that an Approver's token is not required.

HTTP Request

GET https://app.procurementexpress.com/api/v3/purchase_orders/:id/override_and_approve

URL Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Company ID

Reject

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/api/v3/purchase_orders/1/reject',
  {
    token: 'reject-token'
  },
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/purchase_orders/1/reject'
  -X GET
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"
  -d "token=reject-token"

{
  "status": true
}

Reject purchase order. You must pass valid reject token to reject the Purchase order.

HTTP Request

GET https://app.procurementexpress.com/api/v3/purchase_orders/:id/reject

URL Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Company ID
token	string	Approver's reject token

Cancel

require 'rest-client'

RestClient.post(
  'https://app.procurementexpress.com/api/v3/purchase_orders/1/cancel',
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/purchase_orders/1/cancel'
  -X POST
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"

{
  "status": true
}

Ability to Cancel purchase order. You can check if user can mark purchase order as cancel or not by checking can_cancel value in Purchase Order Details page

HTTP Request

POST https://app.procurementexpress.com/api/v3/purchase_orders/:id/cancel

URL Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Company ID

Mark as Paid

To mark Purchase Order as paid you need to check out Payments API endpoint. Before marking purchase order as paid You might need to check whether given user have enough permission to perform this action. You can find can_mark_as_paid in Purchase Order Details

Receiving Items

require 'rest-client'

RestClient.post(
  'https://app.procurementexpress.com/api/v3/purchase_orders/1/receiving_items',
  {
    purchase_order: {
      items: [
        { id: 1, quantity: 10 },
        { id: 2, quantity: 10 },
        { id: 3, quantity: 20 },
      ],
      notes: 'Item delivered successfully!',
      delivered_on: '2017-1-1'
    }
  }
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/purchase_orders/1/receiving_items'
  -X POST
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"
  -d "purchase_order[items][0][id]=1"
  -d "purchase_order[items][0][quantity]=10"
  -d "purchase_order[items][1][id]=2"
  -d "purchase_order[items][1][quantity]=10"
  -d "purchase_order[items][2][id]=3"
  -d "purchase_order[items][2][quantity]=20"
  -d "purchase_order[delivered_on]=2017-1-1"
  -d "purchase_order[notes]=Item delivered successfully!"

{
  "status": true
}

You can find can_receive_item in Purchase Order Details page, This value should be true in order to allow user to receive items.

HTTP Request

POST https://app.procurementexpress.com/api/v3/purchase_orders/:id/receiving_items

URL Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Company ID
notes	string	comment/notes
delivered_on	string	value must be in valid date format
items[][id]	array[]	list of item ids
items[][quantity]	array[]	list of item quantities

Cancel Receiving Items

require 'rest-client'

RestClient.post(
  'https://app.procurementexpress.com/api/v3/purchase_orders/1/cancel_receiving_items',
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/purchase_orders/1/cancel_receiving_items'
  -X POST
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"

{
  "status": true
}

You can find can_cancel_receiving_items in Purchase Order Details page, the users who are able to receive items can also cancel them. so please make sure this property is set to true.

HTTP Request

POST https://app.procurementexpress.com/api/v3/purchase_orders/:id/cancel_receiving_items

URL Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Company ID

Invoices

List Invoices

RestClient.get(
  "https://app.procurementexpress.com/api/v3/invoices",
  headers = {
    app_company_id: 1,
    authentication_token: "your token"
  }
)

curl "https://app.procurementexpress.com/api/v3/invoices"
  -X GET
  -H "Content-Type: application/json"
  -H "app_company_id: 1"
  -H "authentication_token: your token"

{
  "invoices": [{
    "id": 1,
    "invoice_number": "Invoice 1",
    "status": "ready_to_pay",
    "issue_date": 1683522000,
    "validation_date": 1683522000,
    "uploaded_date": 1683522000,
    "due_date": 1683522000,
    "tax_amount": 150.0,
    "net_amount": 1000.0,
    "gross_amount": 1150.0,
    "balance_amount": 1150.0,
    "supplier_id": 1,
    "supplier_name": "Supplier Name",
    "purchase_order_references": [{
      "1-1970-01-01"
    }],
    "can_accept": true,
    "can_approve": false,
    "can_reject": false,
    "can_cancel": true,
    "can_archive": true,
    "can_dearchive": false,
    "currency": {
      "id": 162,
      "iso_code": "ZAR",
      "iso_numeric": 710,
      "name": "South African Rand",
      "symbol": "R",
      "created_at": "2015-01-01T04:21:56.144-06:00",
      "updated_at": "2023-05-08T03:02:08.904-05:00"
    }
  }],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 49
  }
}

List all invoices for the Company indicated by app_company_id.

Pagination

The Invoice list returned is paginated with 100 records per page. You can find details on the current page and total number of pages under the meta attributes in the JSON repsonse. You can enter additioal pages by passing the page argument as follows: https://app.procurementexpress.com/api/v3/invoices?page=2

Filtering

A variety of filters can be applied to the list by adding additional parameters, e.g. archived, like follows: https://app.procurementexpress.com/api/v3/invoices?archived=false

Please see the Query Parameters for a complete list of potential filter arguments.

HTTP Request

GET /api/v3/invoices

Query Parameters

Params	Type	Options	Description
app_company_id	header		Company ID number
authentication_token	header		Authentication Token
archived	boolean	`true` or `false`	Whether the Invoice(s) are archived or not
requester_id	number		The ID Number of the user thgat requested the Invoice(s)
approver_id	number		The ID Number of the user that approved the Invoice(s)
supplier_id	number		The ID Number of the supplier the Invoice(s) are associated with
invoice_date_filter	string	"last 7days"	The date-range filter for the updated date with which to filter the Invoice(s) by
page	number		The page number for which results are returned (see `Pagination`)

Invoice Details

RestClient.get(
  "https://app.procurementexpress.com/api/v3/invoices/1",
  headers = {
    app_company_id: 1,
    authentication_token: "your token"
  }
)

curl "https://app.procurementexpress.com/api/v3/invoices/1"
  -X GET
  -H "Content-Type: application/json"
  -H "app_company_id: 1"
  -H "authentication_token: your token"

This endpoint gives acces to detailed information about a specific Invoice.

HTTP Request

GET /api/v3/invoices/:id

Query Parameters

Params	Type	Description
app_company_id	header	Company ID number
authentication_token	header	Authentication Token

Create an Invoice

RestClient.post(
  "https://app.procurementexpress.com/api/v3/invoices",
  {
    "invoice": {
        "gross_amount": "20.00",
        "due_date": "2023-05-17",
        "uploaded_date": "2023-05-16",
        "currency_id": 1000,
        "company_id": 20000,
        "invoice_number": "inv-001",
        "supplier_id": 131,
        "issue_date": "2023-05-16",
        "received_date": "2023-05-16",
        "invoice_line_items_attributes": [
            {
                "sequence_no": 1,
                "description": "Advertising",
                "unit_price": "100",
                "quantity": "10",
                "vat": "5",
                "net_amount": 1000,
                "purchase_order_id": 30000,
                "purchase_order_item_id": 433
            }
        ],
        "supplier_invoice_uploads_attributes": [{
          "id": null,
          "file": null
        }]
    }
},
  headers = {
    app_company_id: 1,
    authentication_token: "your token"
  }
)

curl "https://app.procurementexpress.com/api/v3/invoices"
  -X POST
  -H "Content-Type: application/json"
  -H "app_company_id: 1"
  -H "authentication_token: your token"
  -d "invoice[invoice_number] = inv-001",
  -d "invoice[issue_date] = 2023-01-01",
  -d "invoice[supplier_id] = null",
  -d "invoice[received_date] = 2023-01-01",
  -d "invoice[due_date] = 2023-02-01",
  -d "invoice[gross_amount] = 1210",
  -d "invoice[currency_id] = 1000",
  -d "invoice[invoice_line_items_attributes][][description] = Airfare",
  -d "invoice[invoice_line_items_attributes][][unit_price] = 1000",
  -d "invoice[invoice_line_items_attributes][][quantity] = 1",
  -d "invoice[invoice_line_items_attributes][][vat] = 21",
  -d "invoice[invoice_line_items_attributes][][net_amount] = 1000",
  -d "invoice[invoice_line_items_attributes][][purchase_order_id] = 2",
  -d "invoice[invoice_line_items_attributes][][purchase_order_item_id] = 1",
  -d "invoice[supplier_invoice_uploads_attributes][][file] = https://po-app-staging.s3.amazonaws.com/supplier_invoice_uploads/files/000/000/007/original/test.pdf?1681894799"

{
  "id": 1,
  "invoice_number": "inv-001",
  "status": "outstanding",
  "issue_date": 1681880400,
  "validation_date": null,
  "uploaded_date": 1681880400,
  "due_date": 1681966800,
  "tax_amount": "0.0",
  "net_amount": "0.0",
  "gross_amount": "20.0",
  "balance_amount": "0.0",
  "created_at": 1681894799,
  "updated_at": 1681894799,
  "currency": {
    "id": 1000,
    "iso_code": "EUR",
    "iso_numeric": "978",
    "name": "Euro",
    "symbol": "€",
    "created_at": "2023-04-19T03:59:57.085-05:00",
    "updated_at": "2023-04-19T03:59:57.367-05:00"
  },
  "supplier": {
    "id": 45,
    "name": "Apple",
    "company_id": 20000,
    "notes": null,
    "phone_number": null,
    "address": null,
    "email": null,
    "payment_details": null,
    "archived": false,
    "contact_person": null,
    "tax_number": null,
    "created_at": "2023-04-19T03:59:57.581-05:00",
    "updated_at": "2023-04-19T03:59:58.820-05:00",
    "currency_id": null,
    "department_ids": [],
    "third_party_id_mappings": [],
    "external_vendor_id": null
  },
  "invoice_line_items": [{
    "id": 9,
    "sequence_no": 1,
    "description": "Advertising",
    "unit_price": "100.0",
    "quantity": "10.0",
    "vat": "5.0",
    "net_amount": "1000.0",
    "base_net_amount": "1000.0",
    "deleted_at": null,
    "billable_status": null,
    "tax_rate_id": null,
    "chart_of_account_id": null,
    "invoice_id": 7,
    "purchase_order_id": 30000,
    "purchase_order_item_id": 90,
    "markup_info": null,
    "created_at": 1681894800,
    "updated_at": 1681894800
  }],
  "purchase_orders": [{
    "id": 30000,
    "approval_key": null,
    "creator_name": "Team Member",
    "amount": "1600.0",
    "status": "pending",
    "supplier_name": "Apple",
    "keywords": "30000 Apple Team Member  pending 1680.00   iPhone 840.0 800.0   iPhone 840.0 800.0",
    "created_at": 1681894796000,
    "currency_id": 1000,
    "currency_symbol": "€",
    "currency_iso_code": "EUR",
    "total_gross_amount": "1680.0",
    "total_net_amount": "1600.0",
    "base_gross_amount": 1680.0,
    "submitted_on": 1681894798000,
    "share_key": "GCFJSAFMLFVGXFBSFIPQXFUEHHMKXQQN20230419035958",
    "department_id": null,
    "department_name": null
  }],
  "supplier_invoice_uploads": [{
    "id": 7,
    "file_file_name": "test.pdf",
    "file_content_type": "application/pdf",
    "file_file_size": 13264,
    "url": "https://po-app-staging.s3.amazonaws.com/supplier_invoice_uploads/files/000/000/007/original/test.pdf?1681894799"
  }],
  "histories": [],
  "comments": []
}

Create a new Invoice for the Company ID mentioned in the header.

HTTP Request

POST /api/v3/invoices

Query Parameters

Params	Type	Description
app_company_id	header	Company ID number
authentication_token	header	Authentication Token
invoice[gross_amount]	string	Gross amount of the invoice
invoice[due_date]	string	Due date of the invoice
invoice[uploaded_date]	string	Date on which the invoice was uploaded
invoice[issue_date]	string	Date on which the invoice was issued
invoice[received_date]	string	Date on which the invoice was received
invoice[currency_id]	string	ID of the currency used for the invoice
invoice[company_id]	string	ID of the company that issued the invoice
invoice[invoice_number]	string	Unique identifier for the invoice
invoice[supplier_id]	string	ID of the supplier that the invoice is being issued to
invoice[invoice_line_items_attributes]	array	An array of invoice line items that belongs to the invoice
invoice[invoice_line_items_attributes][][description]	string	Description of the invoice line item
invoice[invoice_line_items_attributes][][unit_price]	string	Price per unit of the invoice line item
invoice[invoice_line_items_attributes][][quantity]	string	Quantity of the invoice line item
invoice[invoice_line_items_attributes][][vat]	string	VAT of the invoice line item
invoice[invoice_line_items_attributes][][net_amount]	string	Net amount of the invoice line item
invoice[invoice_line_items_attributes][][purchase_order_id]	string	ID of the purchase order associated with the invoice line item
invoice[invoice_line_items_attributes][][purchase_order_item_id]	string	ID of the purchase order item associated with the invoice line item
invoice[supplier_invoice_uploads_attributes][][file]	string	The uploaded invoice file URL

Update an Invoice

RestClient.put(
  "https://app.procurementexpress.com/api/v3/invoices/:id",
  {
    "invoice": {
        "gross_amount": "20.00",
        "due_date": "2023-05-17",
        "uploaded_date": "2023-05-16",
        "currency_id": 1000,
        "company_id": 20000,
        "invoice_number": "inv-001",
        "supplier_id": 131,
        "issue_date": "2023-05-16",
        "received_date": "2023-05-16",
        "invoice_line_items_attributes": [
            {
              "id": null,
              "sequence_no": 1,
              "description": "Advertising",
              "unit_price": "100",
              "quantity": "10",
              "vat": "5",
              "net_amount": 1000,
              "purchase_order_id": 30000,
              "purchase_order_item_id": 433
            },
            {
              "id": 1,
              "sequence_no": 1,
              "description": "Advertising",
              "unit_price": "100",
              "quantity": "10",
              "vat": "5",
              "net_amount": 1000,
              "purchase_order_id": 30000,
              "purchase_order_item_id": 433,
              "_destroy": 1
            },
        ],
        "supplier_invoice_uploads_attributes": [{
          "id": null,
          "file": null
        }]
    },
  headers = {
    app_company_id: 1,
    authentication_token: "your token"
  }
)

curl "https://app.procurementexpress.com/api/v3/invoices/:id"
  -X PUT
  -H "Content-Type: application/json"
  -H "app_company_id: 1"
  -H "authentication_token: your token"
  -d "action: create"
  -d "invoice[invoice_number] = inv-001",
  -d "invoice[issue_date] = 2023-01-01",
  -d "invoice[supplier_id] = null",
  -d "invoice[received_date] = 2023-01-01",
  -d "invoice[due_date] = 2023-02-01",
  -d "invoice[gross_amount] = 1210",
  -d "invoice[currency_id] = 1000",
  -d "[invoice[invoice_line_items_attributes][][description] = Airfare",
  -d "[invoice[invoice_line_items_attributes][][unit_price] = 1000",
  -d "[invoice[invoice_line_items_attributes][][quantity] = 1",
  -d "[invoice[invoice_line_items_attributes][][vat] = 21",
  -d "[invoice[invoice_line_items_attributes][][net_amount] = 1000",
  -d "[invoice[invoice_line_items_attributes][][purchase_order_id] = 2",
  -d "[invoice[invoice_line_items_attributes][][purchase_order_item_id] = 1",
  -d "[supplier_invoice_uploads_attributes][][file] = https://po-app-staging.s3.amazonaws.com/supplier_invoice_uploads/files/000/000/007/original/test.pdf?1681894799"

{
  "id": 1,
  "invoice_number": "inv-001",
  "status": "outstanding",
  "issue_date": 1681880400,
  "validation_date": null,
  "uploaded_date": 1681880400,
  "due_date": 1681966800,
  "tax_amount": "0.0",
  "net_amount": "0.0",
  "gross_amount": "20.0",
  "balance_amount": "0.0",
  "created_at": 1681894799,
  "updated_at": 1681894799,
  "currency": {
    "id": 1000,
    "iso_code": "EUR",
    "iso_numeric": "978",
    "name": "Euro",
    "symbol": "€",
    "created_at": "2023-04-19T03:59:57.085-05:00",
    "updated_at": "2023-04-19T03:59:57.367-05:00"
  },
  "supplier": {
    "id": 45,
    "name": "Apple",
    "company_id": 20000,
    "notes": null,
    "phone_number": null,
    "address": null,
    "email": null,
    "payment_details": null,
    "archived": false,
    "contact_person": null,
    "tax_number": null,
    "created_at": "2023-04-19T03:59:57.581-05:00",
    "updated_at": "2023-04-19T03:59:58.820-05:00",
    "currency_id": null,
    "department_ids": [],
    "third_party_id_mappings": [],
    "external_vendor_id": null
  },
  "invoice_line_items": [{
    "id": 9,
    "sequence_no": 1,
    "description": "Advertising",
    "unit_price": "100.0",
    "quantity": "10.0",
    "vat": "5.0",
    "net_amount": "1000.0",
    "base_net_amount": "1000.0",
    "deleted_at": null,
    "billable_status": null,
    "tax_rate_id": null,
    "chart_of_account_id": null,
    "invoice_id": 7,
    "purchase_order_id": 30000,
    "purchase_order_item_id": 90,
    "markup_info": null,
    "created_at": 1681894800,
    "updated_at": 1681894800
  }],
  "purchase_orders": [{
    "id": 30000,
    "approval_key": null,
    "creator_name": "Team Member",
    "amount": "1600.0",
    "status": "pending",
    "supplier_name": "Apple",
    "keywords": "30000 Apple Team Member  pending 1680.00   iPhone 840.0 800.0   iPhone 840.0 800.0",
    "created_at": 1681894796000,
    "currency_id": 1000,
    "currency_symbol": "€",
    "currency_iso_code": "EUR",
    "total_gross_amount": "1680.0",
    "total_net_amount": "1600.0",
    "base_gross_amount": 1680.0,
    "submitted_on": 1681894798000,
    "share_key": "GCFJSAFMLFVGXFBSFIPQXFUEHHMKXQQN20230419035958",
    "department_id": null,
    "department_name": null
  }],
  "supplier_invoice_uploads": [{
    "id": 7,
    "file_file_name": "test.pdf",
    "file_content_type": "application/pdf",
    "file_file_size": 13264,
    "url": "https://po-app-staging.s3.amazonaws.com/supplier_invoice_uploads/files/000/000/007/original/test.pdf?1681894799"
  }],
  "histories": [],
  "comments": []
}

Update an Invoice. Always pass the id of an existing items including Invoice, invoice_line_items_attributes and so on this will help us update your existing items.

Deleting Existing invoice line items

If you want to delete existing line items from server, than you need to pass id for those line items as well as "_destroy": 1, check example JSON request for example

Eample:

{
  "invoice": {
    ....
    "invoice_line_items_attributes": [
      {
        "id": 1,
        "_destroy": 1,
        ...
      }
    ]
  }
}

HTTP Request

PUT /api/v3/invoices/:id

Query Parameters

Params	Type	Description
app_company_id	header	Company ID number
authentication_token	header	Authentication Token
invoice[gross_amount]	string	Gross amount of the invoice
invoice[due_date]	string	Due date of the invoice
invoice[uploaded_date]	string	Date on which the invoice was uploaded
invoice[issue_date]	string	Date on which the invoice was issued
invoice[received_date]	string	Date on which the invoice was received
invoice[currency_id]	string	ID of the currency used for the invoice
invoice[company_id]	string	ID of the company that issued the invoice
invoice[invoice_number]	string	Unique identifier for the invoice
invoice[supplier_id]	string	ID of the supplier that the invoice is being issued to
invoice[invoice_line_items_attributes][][id]	id	Pass id if it is existing item, pass `null` for new item
invoice[invoice_line_items_attributes][][description]	string	Description of the invoice line item
invoice[invoice_line_items_attributes][][unit_price]	string	Price per unit of the invoice line item
invoice[invoice_line_items_attributes][][quantity]	string	Quantity of the invoice line item
invoice[invoice_line_items_attributes][][vat]	string	VAT of the invoice line item
invoice[invoice_line_items_attributes][][net_amount]	string	Net amount of the invoice line item
invoice[invoice_line_items_attributes][][purchase_order_id]	string	ID of the purchase order associated with the invoice line item
invoice[invoice_line_items_attributes][][purchase_order_item_id]	string	ID of the purchase order item associated with the invoice line item
invoice[supplier_invoice_uploads_attributes][id]	id	Id if it is existing upload item pass `null` for new item
invoice[supplier_invoice_uploads_attributes][file]	string	The uploaded invoice file URL

Create a Comment

RestClient.post(
  "https://app.procurementexpress.com/api/v3/invoices/1/create_comment",
  {
    comment: "write a comment"
  }
  headers = {
    app_company_id: 1,
    authentication_token: "your token"
  }
)

curl "https://app.procurementexpress.com/api/v3/invoices/1/create_comment"
  -X POST
  -H "Content-Type: application/json"
  -H "app_company_id: 1"
  -H "authentication_token: your token"
  -d "comment: write a comment"

{
  "id": 21,
  "comment": "new comment",
  "invoice_id": 296,
  "creator_id": 41000,
  "creator_name": "Team Member",
  "created_at": 1681988035,
  "updated_at": 1681988035,
  "comment_formatted_time": "05:53",
  "comment_formatted_date": "2023-04-20",
  "formatted_comment": "<p>new comment</p>"
}

HTTP Request

POST /api/v3/invoices/:id/create_comment

Query Parameters

Params	Type	Description
app_company_id	header	Company ID number
authentication_token	header	Authentication Token
comment	string	Text to be added as a comment

Accept an awaiting review invoices

If your invoice status is in awaiting_review status and you are authorized to perform and accept action on the invoice. You can check Invoice List or Invoice Detail API response which includes can_accept boolean value. If it is true current logged in user can accept an invoice, otherwise they can not accept.

RestClient.put(
  "https://app.procurementexpress.com/api/v3/invoices/:id/accept",
  headers = {
    app_company_id: 1,
    authentication_token: "your token"
  }
)

curl "https://app.procurementexpress.com/api/v3/invoices/:id/accept"
  -X PUT
  -H "Content-Type: application/json"
  -H "app_company_id: 1"
  -H "authentication_token: your token"

{
  "success": true
}

Accept an Invoice scan in the Awaiting Review status.

HTTP Request

PUT /api/v3/invoices/:id/accept

Query Parameters

Params	Type	Options	Description
app_company_id	header		Company ID number
authentication_token	header		Authentication Token

Approve an Invoice

RestClient.put(
  "https://app.procurementexpress.com/api/v3/1/invoices/approve",
  headers = {
    app_company_id: 1,
    authentication_token: "your token"
  }
)

curl "https://app.procurementexpress.com/api/v3/1/invoices/approve"
  -X PUT
  -H "Content-Type: application/json"
  -H "app_company_id: 1"
  -H "authentication_token: your token"

{
  "success": true
}

Approve an Invoice in the Pending status.

HTTP Request

PUT /api/v3/invoices/:id/approve

Query Parameters

Params	Type	Options	Description
app_company_id	header		Company ID number
authentication_token	header		Authentication Token

Reject an Invoice

RestClient.put(
  "https://app.procurementexpress.com/api/v3/invoices/1/reject",
  headers = {
    app_company_id: 1,
    authentication_token: "your token"
  }
)

curl "https://app.procurementexpress.com/api/v3/invoices/1/reject"
  -X PUT
  -H "Content-Type: application/json"
  -H "app_company_id: 1"
  -H "authentication_token: your token"

{
  "success": true
}

Reject an Invoice in the Pending status.

HTTP Request

PUT /api/v3/invoices/:id/reject

Query Parameters

Params	Type	Options	Description
app_company_id	header		Company ID number
authentication_token	header		Authentication Token

Cancel an Invoice

RestClient.put(
  "https://app.procurementexpress.com/api/v3/invoices/1/cancel",
  headers = {
    app_company_id: 1,
    authentication_token: "your token"
  }
)

curl "https://app.procurementexpress.com/api/v3/purchase_orders/1/cancel"
  -X PUT
  -H "Content-Type: application/json"
  -H "app_company_id: 1"
  -H "authentication_token: your token"

{
  "success": true
}

Cancel an existing Invoice.

HTTP Request

PUT /api/v3/invoices/:id/cancel

Query Parameters

Params	Type	Options	Description
app_company_id	header		Company ID number
authentication_token	header		Authentication Token

Archive an Invoice

RestClient.put(
  "https://app.procurementexpress.com/api/v3/invoices/1/archive",
  headers = {
    app_company_id: 1,
    authentication_token: "your token"
  }
)

curl "https://app.procurementexpress.com/api/v3/purchase_orders/1/archive"
  -X PUT
  -H "Content-Type: application/json"
  -H "app_company_id: 1"
  -H "authentication_token: your token"

{
  "success": true
}

Archive an existing Invoice.

HTTP Request

PUT /api/v3/invoices/:id/archive

Query Parameters

Params	Type	Options	Description
app_company_id	header		Company ID number
authentication_token	header		Authentication Token

Dearchive an Invoice

RestClient.put(
  "https://app.procurementexpress.com/api/v3/invoices/1/dearchive",
  headers = {
    app_company_id: 1,
    authentication_token: "your token"
  }
)

curl "https://app.procurementexpress.com/api/v3/purchase_orders/1/dearchive"
  -X PUT
  -H "Content-Type: application/json"
  -H "app_company_id: 1"
  -H "authentication_token: your token"

{
  "success": true
}

Dearchive an archived Invoice.

HTTP Request

PUT /api/v3/invoices/:id/dearchive

Query Parameters

Params	Type	Options	Description
app_company_id	header		Company ID number
authentication_token	header		Authentication Token

Payments

Create a Payment (Feature flagged)

require 'rest-client'

RestClient.post(
  'https://app.procurementexpress.com/api/v3/npayments',
  {
    npayment: {
        user_id: 1,
        reference: "PAY001",
        supplier_id: 1,
        ptype: "bank_transfer",
        date: "2024-06-04",
        currency_id: 3,
        amount: 100,
        npayment_invoices_attributes: [
            {
                invoice_id: 1,
                gross_amount: 100,
                _destroy: false
            }
        ],
        npayment_comments_attributes: [
            {
                creator_id: 1,
                comment: "Payment comment goes here...",
                system_generated: false
            }
        ]
    }
  },
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/npayments'
  -X POST
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"
  -d '{
    "npayment": {
        "user_id": 1,
        "reference": "PAY001",
        "supplier_id": 1,
        "ptype": "bank_transfer",
        "date": "2024-06-04",
        "currency_id": 3,
        "amount": 100,
        "npayment_invoices_attributes": [
            {
                "invoice_id": 1,
                "gross_amount": 100,
                "_destroy": false
            }
        ],
        "npayment_comments_attributes": [
            {
                "creator_id": 1,
                "comment": "Payment comment goes here...",
                "system_generated": false
            }
        ]
    }
}'

{
  "id": 1,
  "reference": "PAY001",
  "status": "active",
  "ptype": "bank_transfer",
  "date": 1717477200,
  "amount": "100.0",
  "created_at": 1717477200,
  "updated_at": 1717477200,
  "payment_mode": "normal",
  "archived": false,
  "conversion_rate": "1.0",
  "currency": {
    "id": 3,
    "name": "United States Dollar",
    "iso_code": "USD",
    "symbol": "$"
  },
  "supplier": {
    "id": 1,
    "name": "Amazon"
  },
  "user": {
    "id": 1,
    "email": "[email protected]",
    "name": "John Doe"
  },
  "invoices": [
    {
      "id": 1,
      "invoice_number": "INV001",
      "status": "settled",
      "issue_date": 1719226800,
      "validation_date": 1719226800,
      "uploaded_date": 1719311984,
      "due_date": 1719226800,
      "tax_amount": "0.0",
      "net_amount": "100.0",
      "gross_amount": "100.0",
      "balance_amount": "0.0",
      "supplier_id": 1,
      "supplier_name": "Amazon",
      "purchase_order_references": [
        "1005"
      ],
      "can_accept": false,
      "can_approve": false,
      "can_reject": false,
      "can_cancel": true,
      "can_archive": true,
      "can_dearchive": false,
      "standalone_invoice": false,
      "confidence_score": "0.0",
      "digital_invoice": false,
      "payment_term_id": 1,
      "payment_terms_list": {
        "id": 1,
        "name": "Due on receipt",
        "archived": false,
        "term_type": "standard",
        "due_days": 0,
        "day_of_month": 0,
        "company_id": 1,
        "created_at": "2023-09-21T07:51:39.325-05:00",
        "updated_at": "2023-09-21T07:53:45.893-05:00"
      }
    }
  ],
  "npayment_comments": [
    {
      "id": 1,
      "comment": "Invoice payment via API",
      "creator_id": 1,
      "system_generated": false,
      "created_at": 1719905090,
      "updated_at": 1719905090
    }
  ]
}

Use this api endpoint to create a Payment, invoice payment and purchase order payment at once. It will also change Invoice status to settled status and purchase order's payment status to paid. can_mark_po_as_paid in the Purchase Order Detail endpoint.

Important Note

This API feature is not available to every please talk to the Success/Sales team about it

Different Statues and their corresponding enum values

status

This is the status of the payment, it has 2 possible values

str_value	enum_value	description
active	0	active payment (default)
cancelled	10	cancelled payment

Use str_value case sensitive value in the JSON request.

example "status": "active"

ptype

This json attribute is to set Payment type and it supports following enums:

str_value	enum_value	description
bank_transfer	0	bank transfer payment
card	10	card payment
credit_card	15	credit card payment
check	20	check payment
cash	25	cash payment
one_time_card	30	one time card payment
letter_of_credit	35	letter of credit payment
other	40	other payment
batch_payment	40	Batch payment

Example: "ptype": "credit_card"

payment_mode

Use this json attribute to set your payment mode

str_value	enum_value	description
normal	0	normal payment (default)
advance	10	advance payment

example: "payment_mode": "normal"

HTTP Request

POST https://app.procurementexpress.com/api/v3/npayments

Query Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Company ID
npayment[user_id]	integer	payment creator id
npayment[reference]	string	payment reference number
npayment[supplier_id]	integer	supplier id for payment
npayment[ptype]	string	payment type, check documentation above for possible values
npayment[date]	string	payment date, make sure to use correct date format
npayment[currency_id]	integer	payment currency id
npayment[amount]	number	payment total amount, must match with sum of invoice amounts
npayment[npayment_invoices_attributes][][invoice_id]	integer	linked invoice id for this payment
npayment[npayment_invoices_attributes][][gross_amount]	integer	invoice original gross amount
npayment[npayment_invoices_attributes][][_destroy]	integer	`true` if you want to delete invoice link in Edit call, otherwise always set `false` or ignore this params
npayment[npayment_comments_attributes][][creator_id]	double	creator id for comment
npayment[npayment_comments_attributes][][comment]	double	user comment for the payment
npayment[npayment_comments_attributes][][system_generated]	double	Always use `false` value, otherwise comment will be displayed in history section.

Create a Purchase Order Payment

require 'rest-client'

RestClient.post(
  'https://app.procurementexpress.com/api/v3/purchase_orders/1/payments',
  {
    payment: {
      notes: "payment notes",
      purchase_order_item_payments_attributes: [
        {
          purchase_order_item_id: 1,
          amount: 10.00
        },
        {
          purchase_order_item_id: 2,
          amount: 20.00
        }
      ]
    }
  },
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/purchase_orders/1/payments'
  -X POST
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"
  -d "payment[notes]=payment notes"
  -d "payment[purchase_order_item_payments_attributes][0][purchase_order_item_id]=1"
  -d "payment[purchase_order_item_payments_attributes][0][amount]=10.00"
  -d "payment[purchase_order_item_payments_attributes][1][purchase_order_item_id]=2"
  -d "payment[purchase_order_item_payments_attributes][1][amount]=20.00"

{
  success: true
}

Use this api endpoint to mark purchase order as paid. To check if authentication_token have enough permission to mark purchase order as paid or not, you need to first check can_mark_po_as_paid in the Purchase Order Detail endpoint.

HTTP Request

POST https://app.procurementexpress.com/api/v3/purchase_orders/:purchase_order_id/payments

Query Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Company ID
payment[note]	string	your notes/comment on this payment
payment[purchase_order_item_payments_attributes][][purchase_order_item_id]	integer	Purchase Order Item ID
payment[purchase_order_item_payments_attributes][][amount]	double	Purchase order Item amount

Suppliers

Create a Supplier

require 'rest-client'

RestClient.post(
  'https://app.procurementexpress.com/api/v3/suppliers',
  {
    supplier: {
      name: 'iCare Center',
      email: '[email protected]',
      address: '234 Saint St.',
      notes: 'purchase iPhone 7'
    }
  }
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/suppliers'
  -X POST
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"
  -d "supplier[name]=iCare Center"
  -d "supplier[email][email protected]"
  -d "supplier[address]=234 Saint St."
  -d "supplier[notes]=purchase iPhone 7"

{
  "id": 1,
  "name": "iCare Center",
  "company_id": 1,
  "external_vendor_id": "X4dDQNpj",
  "notes": "purchase iPhone 7",
  "phone_number": null,
  "address": "234 Saint St.",
  "email": "[email protected]",
  "payment_details": null,
  "archived": false,
  "contact_person": null,
  "tax_number": null
}

Create a new suppliers and returns the Supplier object that is created.

HTTP Request

POST https://app.procurementexpress.com/api/v3/suppliers

Query Parameters

Params	Type	description
authentication_token	header	Authentication token
app_company_id	header	Company ID
supplier[name]	string	Supplier name must present and should be unique
supplier[email]	string	Email address
supplier[address]	string	Supplier address
supplier[notes]	string	Notes
supplier[payment_details]	string	Payment Details
supplier[phone_number]	string	Phone Number
supplier[archived]	boolean	Archived?
supplier[tax_number]	string	TAX Number
supplier[contact_person]	string	Contact Person
department_ids	array[]	List of Department IDs

Get all Suppliers

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/api/v3/suppliers',
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/suppliers'
  -X GET
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"

[
  {
    "id": 1,
    "name": "iCare Center",
    "company_id": 1,
    "external_vendor_id": "X4dDQNpj",
    "notes": "purchase iPhone 7",
    "phone_number": null,
    "address": "234 Saint St.",
    "email": "[email protected]",
    "payment_details": null,
    "archived": false,
    "contact_person": null,
    "tax_number": null
  }
]

{
  "suppliers": [
    {
      "id": 1,
      "name": "iCare Center",
      "company_id": 1,
      "external_vendor_id": "X4dDQNpj",
      "notes": "purchase iPhone 7",
      "phone_number": null,
      "address": "234 Saint St.",
      "email": "[email protected]",
      "payment_details": null,
      "archived": false,
      "contact_person": null,
      "tax_number": null
    }
  ],
  "meta": {
    "current_page": 2,
    "next_page": 3,
    "prev_page": 1,
    "total_pages": 62,
    "total_count": 1239
  }
}

Returns a list of suppliers.

Pagination

You can paginate records by passing page params, example: /api/v3/suppliers?page=2. If you enable pagination, the output will include meta object which contains information like current_page, next_page, previous_page, total_pages and total_count. You can use these information to write your own pagination logic.

Top n records

You can also find top n suppliers by passing top params. /api/v3/suppliers/top?top=10

Filter Suppliers by department

To filter suppliers for specific department you can pass department_id in queryparams. example: /api/v3/suppliers?department_id=1.

Filter Archived Suppliers

You can pass archived params with true or false to filter Archived suppliers.

About `external_vendor_id`

We can now see external_vendor_id for supplier in json response. The value of this field can be set from ProcurementExpress.com web application (see screenshot below). This value is unique per companies that is 2 suppliers from same companies can't have duplicate external_vendor_id. Maximum characters supported in this field is 64 characters.

HTTP Request

GET https://app.procurementexpress.com/api/v3/suppliers

Query Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Company ID
page	integer	Page number to paginate
department_id	integer	filter suppliers by department
archived	boolean	`true` or `false` to filter archived suppliers
top	integer	limit n record

Get Supplier details

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/api/v3/suppliers/1',
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/suppliers/1'
  -X GET
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"

{
  "id": 1,
  "name": "iCare Center",
  "company_id": 1,
  "external_vendor_id": "X4dDQNpj",
  "notes": "purchase iPhone 7",
  "phone_number": null,
  "address": "234 Saint St.",
  "email": "[email protected]",
  "payment_details": null,
  "archived": false,
  "contact_person": null,
  "tax_number": null
  }

Retrieves the details of an existing suppliers. You need to supply the unique supplier id, that was returned upon supplier creation.

HTTP Request

GET https://app.procurementexpress.com/api/v3/suppliers/:id

URL Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Company ID
ID	integer	Supplier ID

Update Supplier

require 'rest-client'

RestClient.put(
  'https://app.procurementexpress.com/api/v3/suppliers/1',
  {
    supplier: {
      name: 'updated'
    }
  }
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/suppliers/1'
  -X PUT
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"
  -d "supplier[name]=updated"

{
  "id": 1,
  "name": "updated",
  "company_id": 1,
  "external_vendor_id": "X4dDQNpj",
  "notes": "purchase iPhone 7",
  "phone_number": null,
  "address": "234 Saint St.",
  "email": "[email protected]",
  "payment_details": null,
  "archived": false,
  "contact_person": null,
  "tax_number": null
}

Update the specified supplier by setting the value of parameters passed. Any parameters not provided will be left unchanged.

HTTP Request

PUT https://app.procurementexpress.com/api/v3/suppliers/:id

Query Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Company ID
supplier[name]	string	Supplier name must present and should be unique
supplier[email]	string	Email address
supplier[address]	string	Supplier address
supplier[notes]	string	Notes
supplier[payment_details]	string	Payment Details
supplier[phone_number]	string	Phone Number
supplier[archived]	boolean	Archived?
supplier[tax_number]	string	TAX Number
supplier[contact_person]	string	Contact Person
department_ids	array[]	List of Department IDs

Send to supplier templates

Get All Templates

curl --request GET \
  --url https://app.procurementexpress.com/api/v3/send_to_supplier_templates \
  --header 'app_company_id: 1' \
  --header 'authentication_token: your token' \
  --header 'content-type: application/json'

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/api/v3/send_to_supplier_templates',
  headers = {
      authentication_token: 'your token',
      app_company_id: '1'
  }
)

[
  {
    "id": 1,
    "company_id": 1,
    "label": "Default Template",
    "text":
      "Dear MyTaxi, \r\n\r\nPlease find attached to this email a Purchase Order number. We request that you attach this document when sending your invoice to our accounts department. \r\n\r\nSincerely, \r\nUNICEF Ireland"
  },
  {
    "id": 2,
    "company_id": 1,
    "label": "Sample Template",
    "text": "Dear John Snow, \r\n\n this is a sample template",
    "is_default": true
  }
]

Get list of all templates.

HTTP Request

GET https://app.procurementexpress.com/api/v3/send_to_supplier_templates

Query Parameters

Params	Type	Description
app_company_id	header	Company ID
authentication_token	header	Authentication Token

Forward Template

curl --request POST \
  --url https://app.procurementexpress.com/api/v3/purchase_orders/2/forward \
  --header 'app_company_id: 1' \
  --header 'authentication_token: your token' \
  --header 'content-type: application/json' \
  --data '{
    "emails": "[email protected]",
    "cc": "[email protected]",
    "note": "Thank you for subscribing",
    "save_template": true,
    "email_subject": "Thank you for subscribing",
    "template_label": "woo hoo!!",
    "uploads": [1,2],
  }'

require 'rest-client'

RestClient.post(
  'https://app.procurementexpress.com/api/v3/purchase_orders/2/forward',
  {
    emails: "[email protected]",
    cc: "[email protected]",
    note: "Thank you for subscribing",
    save_template: true,
    email_subject: "Thank you for subscribing",
    template_label: "woo hoo!!",
    uploads: [1,2]
  },
  headers = {
    authentication_token: 'your token',
    app_company_id: '1'
  }
)

{ "save": true }

This api endpoint will perform any of these 3 actions:

Create New Template

To create new template, you must pass save_template: true params or form data into the post request.

Update Existing Template

To update existing template, you must need to pass update_template: true params or form data into this post request.

Send template to supplier

If save_template or update_template is not there, then it will send given template to the supplier.

Default Template

To mark template as default, you need to pass is_default: true params or form data.

Emails Fields

In Purchase Order Details you will get supplier.email, which you can send in emails field.

CC Fields

In Purchase Order Details you will get creator_email, you can set that value in cc field.

Uploads Fields

uploads accept list of ids, and must be Array values. If uploads are send while saving or updating template, they are ignored. uploads are only available when you are sending template to the supplier.

HTTP Request

POST https://app.procurementexpress.com/api/v3/purchase_orders/:id/forward

Query Parameters

Param	Type	Description
authentication_token	header	Authentication token
app_company_id	header	registered company id
emails	Array	list of email addresses
cc	string	CC email address
notes	text	template body
email_subject	string	Email subject
template_label	string	Template Label
save_template	boolean	`true` if you want to save template
is_default	boolean	`true` if you want to mark template as default
update_template	boolean	`true` if you want to update template
uploads	Array	list of upload ids

Tax Rates

Get All Tax Rates

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/api/v3/tax_rates',
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/tax_rates'
  -X GET
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"

[
  {
    "id": 1,
    "name": "default_13.0",
    "value": 13,
    "archived": false,
    "company_id": 1,
    "tax_type": "single",
    "created_at": "2017-08-08T06:32:28.224-05:00",
    "updated_at": "2017-08-08T06:32:28.224-05:00"
  },
  {
    "id": 2,
    "name": "GST/QST QC",
    "value": 14.975,
    "archived": false,
    "company_id": 1,
    "tax_type": "combined",
    "tax_rate_items": [
      {
        "id": 1,
        "combined_tax_rate": {
          "id": 71720,
          "name": "GST",
          "value": 5.0
        }
      },
      {
        "id": 2,
        "combined_tax_rate": {
          "id": 71721,
          "name": "QST QC",
          "value": 9.975
        }
      }
    ],
    "created_at": "2017-08-08T06:32:28.111-05:00",
    "updated_at": "2017-08-08T06:32:28.111-05:00"
  }
]

Returns a list of your tax rates.

HTTP Request

GET https://app.procurementexpress.com/api/v3/tax_rates

Tax rate type

We support two types of tax rates Single and Combined. All Tax rates are by default Single tax rates. But in some countries like Canada there are grouped/combined tax rates like GST/QST QC (14.975) which is a combination of 2 tax rates GST (5.0) and QST QC (9.975), in that case you can create a combined tax rate by setting Tax Type to Combined and by selecting all the Single tax rates that are applied to that combined tax rate. Go to ProcurementExpress.com -> Settings -> Company Setting -> Tax -> Create New Tax to create either Single or Combined tax rate.

Example screenshot for Creating Single tax rate

Example screenshot for Creating Combined tax rate

Query Parameters

Param	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Company ID

Create a Tax Rate

require 'rest-client'

RestClient.post(
  'https://app.procurementexpress.com/api/v3/tax_rates',
  {
    tax_rate: {
      name: 'default_13.0',
      value: '13'
    }
  },
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/tax_rates'
  -X POST
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"
  -d "tax_rate[name]=default_13.0"
  -d "tax_rate[value]=13"

{
  "id": 1,
  "name": "default_13.0",
  "value": 13,
  "archived": false,
  "company_id": 1,
  "tax_type": "single",
  "created_at": "2017-09-08T06:32:28.224-05:00",
  "updated_at": "2017-09-08T06:32:28.224-05:00"
}

Create a new Tax rate and return the TaxRate object that is created.

HTTP Request

POST https://app.procurementexpress.com/api/v3/tax_rates

Query Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Company Id
tax_rate[name]	string	Tax rate name
tax_rate[value]	string	Tax rate value
tax_rate[archived]	boolean	Archived?
tax_rate[comapny_id]	integer	Company ID

Get a Specific Tax Rates

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/api/v3/tax_rates/1',
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/tax_rates/1'
  -X GET
  -H 'Content-Type: application/json'
  -H 'authentication_token: your token'
  -H 'app_company_id: 1'

{
  "id": 1,
  "name": "default_13.0",
  "value": 13,
  "archived": false,
  "company_id": 1,
  "tax_type": "single",
  "created_at": "2017-08-08T06:32:28.224-05:00",
  "updated_at": "2017-08-08T06:32:28.224-05:00"
}

Retrieves the details of an existing tax rates. You need to supply the tax rate id, that was returned upon tax rate creation.

HTTP Request

GET https://app.procurementexpress.com/api/v3/tax_rates/:id

URL Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Company ID
ID	integer	TaxRate ID

Update a Tax Rate

require 'rest-client'

RestClient.put(
  'https://app.procurementexpress.com/api/v3/tax_rates/1',
  {
    tax_rate: {
      name: 'default_13.10',
      value: '13.10'
    }
  },
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/tax_rates/1'
  -X PUT
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"
  -d "tax_rate[name]=default_13.10"
  -d "tax_rate[value]=13.10"

{
  "id": 1,
  "name": "default_13.10",
  "value": 13.10,
  "archived": false,
  "company_id": 1,
  "tax_type": "single",
  "created_at": "2017-09-08T06:32:28.224-05:00",
  "updated_at": "2017-09-08T06:32:28.224-05:00"
}

Update the specified tax rate by setting the value of parameters passed. Any parameters not provided will be left unchanged.

HTTP Request

PUT https://app.procurementexpress.com/api/v3/tax_rates/:id

Query Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Company ID
tax_rate[name]	string	Tax rate name
tax_rate[value]	string	Tax rate value
tax_rate[archived]	boolean	Archived?
tax_rate[comapny_id]	integer	Company ID

Uploads

Purchase Order Upload

require 'rest-client'

RestClient.post(
  'https://app.procurementexpress.com/api/v3/uploads/po',
  {
    po_id: '1',
    uploads_attributes: {
      upload_token: 'myuploadtoken',
      file: 'file upload field value'
    }
  },
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/uploads/po'
  -X POST
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"
  -d "po_id=1"
  -d "uploads_attributes[upload_token]=myuploadtoken"
  -d "uploads_attributes[file]=file upload field value"

{
  "id": 1,
  "file_file_name": "purchase_order.png",
  "file_content_type": "image/png",
  "url": "https://s3-eu-west-1.amazonaws.com/bucket/uploads/files/000/100/959/original/myAvatar.png?1505993714",
  "upload_token": "myuploadtoken"
}

Add upload for Purchase Order, upload it to s3, and then returns the content in json format.

HTTP Request

POST https://app.procurementexpress.com/api/v3/uploads/po

URL Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Company ID
po_id	integer	Purchase Order ID
uploads_attributes[upload_token]	string	Upload Token
uploads_attributes[file]	file	File field

PO Comment Upload

require 'rest-client'

RestClient.post(
  'https://app.procurementexpress.com/api/v3/uploads/poc',
  {
    poc_id: '1',
    uploads_attributes: {
      upload_token: 'myuploadtoken1',
      file: 'file upload field value'
    }
  },
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/uploads/poc'
  -X POST
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"
  -d "poc_id=1"
  -d "uploads_attributes[upload_token]=myuploadtoken1"
  -d "uploads_attributes[file]=file upload field value"

{
  "id": 1,
  "file_file_name": "purchase_order_comment.png",
  "file_content_type": "image/png",
  "url": "https://s3-eu-west-1.amazonaws.com/bucket/uploads/files/001/100/959/original/myAvatar.png?1505993715",
  "upload_token": "myuploadtoken1"
}

Add upload for Purchase Order, upload it to s3, and then returns the content in json format.

HTTP Request

POST https://app.procurementexpress.com/api/v3/uploads/poc

URL Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Company ID
poc_id	integer	Purchase Order Comment ID
uploads_attributes[upload_token]	string	Upload Token
uploads_attributes[file]	file	File field

Get Status

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/api/v3/uploads/status?upload_token=myuploadtoken1',
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/uploads/status?upload_token=myuploadtoken1'
  -X GET
  -H "authentication_token: your token"
  -H "app_company_id: 1"

{
  "id": 1,
  "file_file_name": "purchase_order_comment.png",
  "file_content_type": "image/png",
  "url": "https://s3-eu-west-1.amazonaws.com/bucket/uploads/files/001/100/959/original/myAvatar.png?1505993715",
  "upload_token": "myuploadtoken1"
}

Expects upload_token to be passed in the url params and return matching upload object in JSON format.

HTTP Request

GET https://app.procurementexpress.com/api/v3/uploads/status?upload_token=your token

URL Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Company ID
upload_token	string	Upload Token in url params

Webhooks

{
  "event": "new_po",
  "object": "PurchaseOrder",
  "payload": {
    "id": 1,
    "company_id": 1,
    "approval_key": null,
    "department_id": 1,
    "department_name": "South",
    "supplier_id": 1,
    "supplier_name": "Top Rated Supplier",
    "supplier_email": "",
    "supplier_address": "",
    "status": "pending",
    "creator_id": 1,
    "currency_id": 65,
    "currency_iso_code": "INR",
    "currency_symbol": "₹",
    "currency_name": "Indian Rupee",
    "creator_name": "John Doe",
    "creator_email": "[email protected]",
    "amount": "1.0",
    "created_at": 1651143873,
    "updated_at": 1651143873,
    "notes": "",
    "total_net_amount": "1.0",
    "total_gross_amount": "1.0",
    "base_gross_amount": 1.0,
    "delivery_status": "not_delivered",
    "delivered_on": null,
    "custom_fields": null,
    "share_key": "PLMLMLVL....20220428070433",
    "archived": false,
    "conversion_rate": "1.0",
    "keywords": "1 Top Rated Supplier John Doe  pending 1.00  Sample Budget Pen 1.0 1.0",
    "self_approved": false,
    "xero_id": null,
    "synced_with_xero": false,
    "custom_field_values": [],
    "url": "https://app.procurementexpress.com/en/purchase_orders/1",
    "purchase_order_items": [
      {
        "id": 1,
        "description": "Pen",
        "purchase_order_id": 1,
        "budget_id": 1,
        "budget_summary": "Sample Budget",
        "gross_amount": "1.0",
        "vat": "0.0",
        "net_amount": "1.0",
        "status": "pending",
        "quantity": "1.0",
        "unit_price": "1.0",
        "item_number": null,
        "base_net_amount": "1.0",
        "base_gross_amount": "1.0",
        "gross_usd_amount": "0.01307",
        "product_id": 1,
        "received_quantity": null,
        "sequence_no": 1,
        "custom_field_values": [],
        "third_party_id_mappings": []
      }
    ],
    "budgets": [
      {
        "id": 1,
        "company_id": 1,
        "name": "Sample Budget",
        "amount": "10000000.0",
        "cost_code": null,
        "cost_type": null,
        "archived": false,
        "currency_id": 65,
        "base_amount": null,
        "base_rate": null,
        "allow_anyone_to_approve_a_po": false,
        "start_date": null,
        "end_date": null,
        "summary": "Sample Budget",
        "third_party_id_mappings": []
      }
    ],
    "purchase_order_comments": [],
    "payments": [],
    "purchase_order_item_payments": [],
    "uploads": [],
    "department": null,
    "supplier": {
      "id": 1,
      "name": "Top Rated Supplier",
      "company_id": 1,
      "notes": "",
      "phone_number": "",
      "address": "",
      "email": "",
      "payment_details": "",
      "archived": false,
      "contact_person": "",
      "tax_number": "",
      "created_at": "2022-04-28T06:03:57.773-05:00",
      "updated_at": "2022-04-28T06:04:33.989-05:00",
      "department_ids": [],
      "third_party_id_mappings": []
    }
  }
}

What are webhooks

Webhooks are notifications about ProcurementExpress entities that are sent to your app. When any event specified on event_type query params occurs, a POST request is sent to the specified url. Webhooks notification configured here are triggered by events in your ProcurementExpress company.

When should I use webhooks

If you use API endpoints, then you will get response only when you call it. But there comes a scenario where you might like to know about the changes in realtime, for example, you want to listen to changes as soon as purchase order is created, approved, delivered or paid, then webhooks makes your life easier, because it send a POST request to your application, as soon as those event occurs in your ProcurementExpress company.

Supported events

Right now we support following webhooks events:

`new_po`

If new_po event is enabled in webhooks configuration, then everytime new purchase order is created in your ProcurementExpress company, a webhooks request is notified. Purchase order status can be either Draft, Pending or Approved depending on your company setting for this event.

`po_approved`

When po_approved event is enabled in webhooks configuration, then everytime a purchase order is approved in your ProcurementExpress company, a webhooks request is notified. Purchase order status will be Approved in this case. And also new unique approval_key for the Purchase Order will be generated by the system based on your approval key setting in the company setting.

`po_delivered`

When po_delivered event is enabled in webhooks configuration, then everytime a purchase order is marked as completely delivered, a webhooks request is notified. Purchase order delivery_status will be complete_delivered meaning items are fully delivered for the purchase order, and also delivered_on field will be recorded with delivery date.

`po_paid`

When po_paid event is enabled in webhooks configuration, then everytime a purchase order is marked as paid, a webhooks request is notified. Purchase order status will be paid.

`po_cancelled`

When po_cancelled event is enabled in webhooks configuration, then everytime a purchase order is marked as cancelled, a webhooks request is notified.

`po_update`

When po_update event is enabled in webhooks configuration, then everytime a purchase order is updated in any state, a webhooks request is notified. And it will send the latest purchase order data in the payload.

Access webhooks in ProcurementExpress application

Login to your company in https://app.procurementexpress.com as companyadmin.
Click on the users menu on the top right corner of the application
click on Integrations menu item
And finally click on Integrate button for Create webhooks based on events section
Here you will see list of webhooks you have configured, and also click on Add Webhooks button to create new one.

Create a Webhook

require 'rest-client'

RestClient.post(
  'https://app.procurementexpress.com/api/v3/webhooks',
  {
    webhook: {
      name: 'My Awesome App',
      url: 'https://myawesomeapp.com/webhook_handler',
      archived: false,
      event_type: [
        "new_po",
        "po_approved",
        "po_delivered",
        "po_paid"
      ],
      json_wrapper: "text",
      send_as_text: false,
      basic_auth_uname: 'myawesomeapp',
      basic_auth_pword: 'securepassw0rd',
      webhook_attributes_attributes: [
        {
          attrib_type: 'root',
          key: 'name',
          value: 'geek'
        },
        {
          attrib_type: 'root',
          key: 'org',
          value: 'My awesome co.'
        },
        {
          attrib_type: 'header',
          key: 'authentication_header',
          value: 'auth-header-goes-here'
        }
      ]
    }
  },
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/webhooks'
  -X POST
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"
  -d "webhook[name]=My Awesome App"
  -d "webhook[url]=https://myawesomeapp.com/webhook_handler"
  -d "webhook[archived]=false"
  -d "webhook[event_type][]=new_po"
  -d "webhook[event_type][]=po_approved"
  -d "webhook[event_type][]=po_delivered"
  -d "webhook[event_type][]=po_paid"
  -d "webhook[json_wrapper]=text"
  -d "webhook[send_as_text]=false"
  -d "webhook[basic_auth_uname]=myawesomeapp"
  -d "webhook[basic_auth_pword]=securepassw0rd"
  -d "webhook[webhook_attributes_attributes][][attrib_type]=root"
  -d "webhook[webhook_attributes_attributes][][key]=name"
  -d "webhook[webhook_attributes_attributes][][value]=geek"
  -d "webhook[webhook_attributes_attributes][][attrib_type]=root"
  -d "webhook[webhook_attributes_attributes][][key]=org"
  -d "webhook[webhook_attributes_attributes][][value]=My awesome co."
  -d "webhook[webhook_attributes_attributes][][attrib_type]=header"
  -d "webhook[webhook_attributes_attributes][][key]=authentication_header"
  -d "webhook[webhook_attributes_attributes][][value]=auth-header-goes-here"

{
  "id": 1,
  "name": "My Awesome App",
  "url": "https://myawesomeapp.com/webhook_handler",
  "archived": false,
  "event_type": [
    "new_po",
    "po_approved",
    "po_delivered",
    "po_paid"
  ],
  "json_wrapper": "text",
  "send_as_text": false,
  "basic_auth_uname": "procurementexpress",
  "basic_auth_pword": "rsrules",
  "webhook_attributes_attributes": [{
    "attrib_type": "root",
    "key": "name",
    "value": "geek"
  },
  {
    "attrib_type": "root",
    "key": "org",
    "value": "My awesome co."
  },
  {
    "attrib_type": "header",
    "key": "authentication_header",
    "value": "auth-header-goes-here"
  }]
}

Create a new Webhooks and returns the Webhook object that is created.

HTTP Request

POST https://app.procurementexpress.com/api/v3/webhooks

Query Parameters

Params	Type	Description
authentication_token	header	Authentication Token
app_company_id	header	Company ID
webhook[name]	string	Name your webhook
webhook[url]	string	Your production URL that will handle webhook request
webhook[archived]	boolean	`true` if you want to archive otherwise `false`
webhook[event_type]	array[]	Event type that you want to trigger when they happen in ProcurementExpress. Supported values are: - `new_po` - `po_approved` - `po_delivered` - `po_paid`
webhook[json_wrapper]	string	Root key that will wrap your json data
webhook[send_as_text]	boolean	`true` if you want to send as plain text, otherwise `false`
webhook[basic_auth_uname]	string	Basic Authorization username
webhook[basic_auth_pword]	string	Basic Authorization password
webhook[webhook_attributes_attribute][][attrib_type]	string	Webhook Nested attributes type
webhook[webhook_attributes_attribute][][key]	string	Webhook Nested attributes key
webhook[webhook_attributes_attribute][][value]	string	Webhook Nested attributes value

Get All Webhooks

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/api/v3/webhooks',
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/webhooks'
  -X GET
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"

[
  {
    "id": 1,
    "name": "My Awesome App",
    "url": "https://myawesomeapp.com/webhook_handler",
    "archived": false,
    "event_type": [
      "new_po",
      "po_approved",
      "po_delivered",
      "po_paid"
    ],
    "tested": true,
    "response_code": null,
    "json_wrapper": "text"
  },
  {
      "id": 2,
      "name": "Slack Events",
      "url": "https://hooks.slack.com/services/...",
      "archived": false,
      "event_type": [
          "new_po",
          "po_approved",
          "po_delivered",
          "po_paid"
      ],
      "tested": false,
      "response_code": null,
      "json_wrapper": "text"
  }
]

Returns a list of webhooks that are not archived.

Filter by archived

Default result will only provide webhooks that are not already archived. If you want to get the list of webhooks that are archived then you can pass archived=true params e.g: https://app.procurementexpress.com/api/v3/webhooks?archived=true

HTTP Request

GET https://app.procurementexpress.com/api/v3/webhooks

Query Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Company ID

Get a specific Webhook

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/api/v3/webhooks/1',
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/webhooks/1'
  -X GET
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"

{
  "id": 1,
  "name": "My Awesome App",
  "url": "https://myawesomeapp.com/webhook_handler",
  "archived": false,
  "event_type": [
    "new_po",
    "po_approved",
    "po_delivered",
    "po_paid"
  ],
  "tested": true,
  "response_code": null,
  "json_wrapper": "text"
}

Retrieves the details of an existing webhooks. You need to supply the unique Webhook id that was returned upon budget creation.

HTTP Request

GET https://app.procurementexpress.com/api/v3/webhooks/:id

URL Parameters

Params	Type	Description
authentication_token	header	Authentication Token
app_company_id	header	Company ID
ID	integer	Webhook ID

Update a Webhook

require 'rest-client'

RestClient.put(
  'https://app.procurementexpress.com/api/v3/webhooks/1',
  {
    webhook: {
      name: 'My Awesome App name updated',
      event_type: [
        "new_po",
        "po_approved"
      ],
    }
  },
  headers = {
    authenticaiton_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/webhooks/1'
  -X PUT
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"
  -d "webhook[name]=My Awesome App name updated"
  -d "webhook[event_type][]=new_po"
  -d "webhook[event_type][]=po_approved"

{
  "id": 1,
  "name": "My Awesome App name updated",
  "url": "https://myawesomeapp.com/webhook_handler",
  "archived": false,
  "event_type": [
    "new_po",
    "po_approved"
  ],
  "json_wrapper": "text",
  "send_as_text": false,
  "basic_auth_uname": "procurementexpress",
  "basic_auth_pword": "rsrules",
  "webhook_attributes_attributes": [{
    "attrib_type": "root",
    "key": "name",
    "value": "geek"
  },
  {
    "attrib_type": "root",
    "key": "org",
    "value": "My awesome co."
  },
  {
    "attrib_type": "header",
    "key": "authentication_header",
    "value": "auth-header-goes-here"
  }]
}

Update the specified Webhook by setting the value of parameters passed. Any parameters not provided will be left unchanged.

HTTP Request

PUT https://app.procurementexpress.com/api/v3/webhooks/:id

Query Parameters

Params	Type	Description
authentication_token	header	Authentication token
app_company_id	header	Company ID
ID	integer	Webhook ID
webhook[name]	string	Name your webhook
webhook[url]	string	Your production URL that will handle webhook request
webhook[archived]	boolean	`true` if you want to archive otherwise `false`
webhook[event_type]	array[]	Event type that you want to trigger when they happen in ProcurementExpress. Supported values are: - `new_po` - `po_approved` - `po_delivered` - `po_paid`
webhook[json_wrapper]	string	Root key that will wrap your json data
webhook[send_as_text]	boolean	`true` if you want to send as plain text, otherwise `false`
webhook[basic_auth_uname]	string	Basic Authorization username
webhook[basic_auth_pword]	string	Basic Authorization password
webhook[webhook_attributes_attribute][][attrib_type]	string	Webhook Nested attributes type
webhook[webhook_attributes_attribute][][key]	string	Webhook Nested attributes key
webhook[webhook_attributes_attribute][][value]	string	Webhook Nested attributes value

Chart of accounts

GET All chart of accounts

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/api/v3/chart_of_accounts',
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/chart_of_accounts'
  -X GET
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"

{
    "chart_of_accounts": [
        {
            "id": 1,
            "name": "Accounts Payable (A/P)",
            "classification": "Liability",
            "account_type": "Accounts Payable",
            "currency_code": "USD",
            "account_number": null,
            "display_name": "Accounts Payable (A/P) - Accounts Payable",
            "archived": false,
            "company_id": 1
        },
        {
            "id": 2,
            "name": "Advertising",
            "classification": "Expense",
            "account_type": "Expense",
            "currency_code": "USD",
            "account_number": null,
            "display_name": "Advertising - Expense",
            "archived": false,
            "company_id": 1
        }
    ],
    "meta": {
        "current_page": 1,
        "next_page": null,
        "prev_page": null,
        "total_pages": 1,
        "total_count": 2
    }
}

Returns a list of active chart of accounts for your current connected QuickBooks account.

Search Classes by fully qualified name

You can search for Account with matching fully qualified name or Account number by passing search query params

GET https://app.procurementexpress.com/api/v3/chart_of_accounts?search=Advertising

HTTP Request

GET https://app.procurementexpress.com/api/v3/chart_of_accounts

Query Parameters

Param	Type	Description
authentication_token	header	Authentication token
app_company_id	header	registered company id
search	queryParams	Search by name

QuickBooks Customers

GET All QuickBooks customers

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/api/v3/qbo_customers',
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/qbo_customers'
  -X GET
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"

{
    "qbo_customers": [
        {
            "id": 1,
            "fully_qualified_name": "Amy's Bird Sanctuary",
            "archived": false,
            "company_id": 1
        },
        {
            "id": 2,
            "fully_qualified_name": "Bill's Windsurf Shop",
            "archived": false,
            "company_id": 1
        }
    ],
    "meta": {
        "current_page": 1,
        "next_page": null,
        "prev_page": null,
        "total_pages": 1,
        "total_count": 2
    }
}

Returns a list of active QuickBooks customers for your current connected QuickBooks account.

Search Classes by fully qualified name

You can search for customer with matching names by passing search query params

GET https://app.procurementexpress.com/api/v3/qbo_customers?search=shop

HTTP Request

GET https://app.procurementexpress.com/api/v3/qbo_customers

Query Parameters

Param	Type	Description
authentication_token	header	Authentication token
app_company_id	header	registered company id
search	queryParams	Search by name

QuickBooks Classes

GET All QuickBooks classes

require 'rest-client'

RestClient.get(
  'https://app.procurementexpress.com/api/v3/qbo_classes',
  headers = {
    authentication_token: 'your token',
    app_company_id: 1
  }
)

curl 'https://app.procurementexpress.com/api/v3/qbo_classes'
  -X GET
  -H "Content-Type: application/json"
  -H "authentication_token: your token"
  -H "app_company_id: 1"

{
    "quickbooks_classes": [
        {
            "id": 1,
            "fully_qualified_name": "East",
            "archived": false,
            "company_id": 1
        },
        {
            "id": 2,
            "fully_qualified_name": "West",
            "archived": false,
            "company_id": 1
        },
        {
            "id": 3,
            "fully_qualified_name": "North",
            "archived": false,
            "company_id": 1
        },
        {
            "id": 4,
            "fully_qualified_name": "South",
            "archived": false,
            "company_id": 1
        }
    ],
    "meta": {
        "current_page": 1,
        "next_page": null,
        "prev_page": null,
        "total_pages": 1,
        "total_count": 4
    }
}

Returns a list of active QuickBooks classes for your current connected QuickBooks account.

Search Classes by fully qualified name

You can search for classes with matching names by passing search query params

GET https://app.procurementexpress.com/api/v3/qbo_classes?search=north

HTTP Request

GET https://app.procurementexpress.com/api/v3/qbo_classes

Query Parameters

Param	Type	Description
authentication_token	header	Authentication token
app_company_id	header	registered company id
search	queryParams	Search by name

Introduction

Authentication

Errors

Internationalization

Country and Regional Support

HTTP Request

Query Parameters

Oauth2 Authentication for V3 Api

Fetch a bearer token (Sign in)

HTTP Request

Query Parameters

Revoke a token (or Sign out)

HTTP Request

HTTP Request

Query Parameters

Check if token is valid

HTTP Request

HTTP Request

Accessing resources with bearer token

HTTP Request

HTTP Request

Users

GET Current User

Available Roles

Check if app_company_id is current employer id

About external_user_id

HTTP Request

URL Parameters

Update User

HTTP Request

Query Parameters

Get My Currencies

HTTP Request

Query Parameters

Get All Currencies

HTTP Request

Query Parameters

Budgets

Create a Budget

Include associated departments and approvers

Date format should match company_setting.date_format

HTTP Request

Query Parameters

GET All Budgets

Filter budgets by department_id

Filter by archived

Return budgets that are active till today

Pagination

HTTP Request

Query Parameters

Get a specific Budget

HTTP Request

URL Parameters

Update a Budget

HTTP Request

Query Parameters

Comments

Add new comment for PO

HTTP Request

Query Parameters

Companies

Create a company

HTTP Request

Query Parameters

Get all companies

HTTP Request

Query Parameters

Get a specific company

HTTP Request

URL Parameters

Approvers

Filter By Department

Filtered By Allow approvers to approve their own request

HTTP Request

URL Parameters

Get All Approvers

HTTP Request

URL Parameters

Get All Employees

HTTP Request

About `external_user_id`

Date format should match `company_setting.date_format`

Filtered By `Allow approvers to approve their own request`