PropRetire

The client API

Published

A grid of rows lying on a plate, one row's answer in coral

A tool adds a firm's clients by sending them to https://www.propretire.com.au/api/v1/clients with the firm's key. Each client goes through the same checks as a row in Import clients, and the answer says which were added and why any weren't. The key reaches nothing else.

What this does for you

A firm's clients added from your own code, each with the reason it was or wasn't added.

1. How do I send clients?

Send a POST with the header Authorization: Bearer followed by the key, and Content-Type: application/json. A firm makes its key in API keys.

  • clients: a list of one or more clients, each with name, and optionally lastName, joined after it, and email.
  • operationId: a new lower case UUID for each request, which makes a retry safe.

For example:

{
  "clients": [{
    "name": "Sarah",
    "lastName": "Jenkins",
    "email": "sarah@example.com"
  }],
  "operationId":
"0f8c2b9e-6d1a-4c55-9a3e-2b7d4f1e8c60"
}

A request can be up to 1 MB, which holds thousands of clients.

2. What comes back?

A 201 with added, the number added, and rows, one for each client sent, in order. Each row has line, its place in the list from 1, and a reason when it was not added.

  • no_name: the name is empty.
  • name_too_long: the name is over 500 characters.
  • email_invalid: the email is not a valid address.
  • name_taken: the firm already has a client of that name.
  • name_repeated: an earlier client in the same list has that name.
  • over_limit: the firm has no room left under its client limit.

clients gives the id and version of each client added. Names are compared whatever their case.

For two clients sent, the second's name already a client's:

{
  "added": 1,
  "rows": [
    { "line": 1 },
    {
      "line": 2,
      "reason": "name_taken"
    }
  ],
  "clients": [{
    "id": "...",
    "version": "..."
  }]
}

3. When is a request refused?

  • 401: the key is missing, wrong or revoked.
  • 403: the adviser who made the key has no two-step verification, or the firm's subscription has ended. The error's code says which.
  • 422: the body is not as above, with fields naming what is wrong.
  • 429: more than 120 requests in 15 minutes for one adviser's keys. Wait the Retry-After seconds.

Each refusal's body is {"error":{"code":"..."}}, and nothing is added.

4. Can I send a request again?

Yes. A request sent again with the same operationId gets the first answer back and adds nothing more. Use a new one for each new request.