Updating Contacts via API

You can add and update Contacts in Payreq Delivery using the Payreq API. This method is generally used where you want to maintain Contact records directly from another system, such as a billing, payroll, or CRM platform, whether you do this yourself or through a mailhouse or technology partner.

The API suits automated Contact updates, recurring synchronisation, and larger operational workflows where manual console updates or SFTP files aren't preferred.

More detail is available in the Payreq Interface Specification, or in the Payreq API tab under Settings.

What the Contacts API is used for

The Contacts API lets an authorised API user send Contact records to Payreq Delivery. Depending on the endpoint used, it can:

• Add new Contacts
• Update existing Contacts
• Replace the full Contact list for a Mailer
• Submit Contact updates as a background job for larger files or data volumes

Payreq uses Contact data to help identify customers, match Subscription requests, and support digital delivery.

Before you begin

Before using the Contacts API, confirm that:

• Your organisation has been set up for Payreq API access (see Managing Users in Payreq Delivery)
• You have an API user with access to the relevant Payreq Delivery account
• You know the correct biller code
• Your Contact field configuration has been confirmed
• You understand whether your update should add/update Contacts or replace the full Contact list
• You have tested the process before using it for production Contact updates

The values required by the API should align with the Contact Field Settings configured for your account. For more detail, see Understanding Contact Field Settings.

Authentication

To use the Payreq API, first authenticate and retrieve an API token. Include the token in the Authorization header for subsequent requests:

Authorization: Token <token>

API tokens are time limited. Their lifetime is configured by the service, so design your integration to request a new token when the current one expires rather than assuming a fixed lifetime.

Contact API endpoints

The Contacts API includes four main endpoints for adding or updating Contacts.

Choosing the correct endpoint

Add Contacts. Use the add endpoint to add new Contacts or update matching existing Contacts. If a Contact already exists with the same biller-account-number, its details are replaced with the values in the request. Use this for incremental updates, such as adding new accounts, updating changed details, correcting existing information, or maintaining Contact data as part of a regular synchronisation.

Replace Contacts. Use the replace endpoint only when the request contains the full Contact list that should remain in Payreq Delivery. Use it carefully, because it refreshes or replaces the existing Contact set for the Mailer. Before using a replace endpoint, confirm that:

• The request contains all required Contacts
• Existing account identifiers have been retained where appropriate
• The possible effect on active Subscriptions has been considered
• The update has been tested and reviewed
• The person or system submitting the request is authorised to perform a full Contact replacement

Job endpoints. For larger Contact volumes, use the job endpoints. These submit the update as a background job and return a job ID. After submitting, monitor processing with the job status endpoint:

GET /biller/{biller-code}/jobs/{job-id}

The current job statuses are pending-file, in-progress, done and error. A job-endpoint response can also report verification errors inside an HTTP 200 response, so inspect the response body before accepting the job ID.

Contact data

The Contacts API accepts a JSON object with the Contact records inside a contacts array. Each Contact must include:

• biller-account-number
• name

The current external contract also defines contact-id-1, auth-item-1 to auth-item-4, business-identifier, name fields and postal-address fields. Which fields you use depends on your organisation's Contact Field Settings. Confirm the mapping for your account before sending Contact updates.

Example Contact payload

This is a simplified example only.

{
  "contacts": [
    {
      "biller-account-number": "123456",
      "name": "Example Customer",
      "contact-id-1": "C123456",
      "auth-item-1": "A123456",
      "address-1": "1 Example Street",
      "municipality": "Melbourne",
      "province": "VIC",
      "postal-code": "3000"
    },
    {
      "biller-account-number": "789012",
      "name": "Second Example Customer",
      "contact-id-1": "C789012",
      "auth-item-1": "A789012"
    }
  ]
}

In this example:

• biller-account-number identifies the Contact record
• name is the customer name stored against the Contact
• contact-id-1 and the auth-item fields hold values defined by your account's Contact Field Settings

The exact fields your organisation uses may be different.

Recommended process

1. Retrieve an API token.
2. Prepare the Contact records in the required JSON format.
3. Validate that each Contact includes the required fields.
4. Submit the request to the appropriate Contact endpoint.
5. Check the API response.
6. For job endpoints, poll the job status endpoint until processing is complete.
7. Investigate any errors or unexpected results.
8. Confirm that the expected Contact records are visible in Payreq Delivery.

Reviewing the response

For standard add or replace requests, a successful response returns a count of processed Contacts and the relevant biller code. For job requests, inspect the complete response: it may contain a job ID, verification errors, or both. Accept the job only after confirming the expected job ID is present and no errors were returned.

If a request fails, review the error response and correct the issue before submitting again.

Common validation issues

• Missing required fields
• Invalid JSON format
• Duplicate biller-account-number values in the same request
• Incorrect biller-account-number length
• Contact field values that do not match the configured field requirements
• Attempting to replace Contacts with an incomplete or unexpected Contact list
• Using the wrong biller code
• Using an expired or incorrectly formatted authentication token