API

The Pigeon API is based on REST. JSON is returned by all API responses, including errors. Currently we only have one official language-specific API library. Let us know if you have developed a library in another language. We can link to other community supported languages.

Official Libraries

Authentication

Authenticate your account by including your secret api key in API requests. Contact Pigeon support to generate your keys. Dashboard management of API keys is coming soon.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

HTTP Status Codes

200 - OK

Everything worked as expected.

401 - Unauthorized

No valid API key provided.

500, 502, 503, 504 - Server Errors

Server errors (very rare)

Customer

Endpoint: /api/customer

find

Use the following example get a customer response back if you have the customer id.

GET /api/customer?client_id=your_client_id&api_key=your_secret_api_key&id=6e4a8f33oreg8jd0ln1

JSON Response

{
  "success": true,
  "customer": {
    "email": "nick@sabramedia.com",
    "display_name": "Nick Johnson",
    "sex": "",
    "dob": "",
    "first_name": "Nick",
    "last_name": "Johnson",
    "group_type": false,
    "id": "6e4a8f33oreg8jd0ln1",
    "parent": [],
    "access": true,
    "plans": [
      {
        "access_id": 3,
        "access_tag": "default",
        "name": "Print + Digital Bundle Monthly $7.00 subscription",
        "start": "2018-05-01",
        "type": 1
      }
    ]
  }
}

search

Endpoint: /api/customer/search

Use this to find customers based on various parameters. Returns an array of results.

search Searches customer name, company name, email, phone, postal code, and third party id (required)

GET Example

GET /api/customer?client_id=your_client_id&api_key=your_secret_api_key&search=pigeon@sabramedia.com

JSON Response

{
  "success": true,
  "results": [
    {
      "id": "xenblda7vh6l6qrs679",
      "display_name": "",
      "full_name": "",
      "email": "pigeon@sabramedia.com",
      "status": "0",
      "authorized": "0",
      "addresses": []
    }
  ]
}

create

The data parameter needs to be a JSON encoded object. Most libraries handle HTTP POST encoding automatically. But keep in mind that the JSON object needs to be encoded via this media type application/x-www-form-urlencoded. This simulates posting a form over the Internet.

JSON Encoded data parameters

display_name Customer's full name (optional)
email Customer's email (required)
password Customer's password (optional)
send_notice Trigger the welcome notice. Default is TRUE. (optional)
internal_id ID of third party system. Can be used to relate the Pigeon customer to third party id. Is visible on profile tab and exports.

POST example

POST /api/customer?client_id=your_client_id&api_key=your_secret_api_key&data=%7B%22display_name%22%3A%22Nick+Johnson%22%2C%22email%22%3A%22pigeon%40sabramedia.com%22%7D

JSON Response

{
  "success": true,
  "customer": {
    "email": "pigeon@sabramedia.com",
    "display_name": "Nick Johnson",
    "sex": null,
    "dob": null,
    "first_name": "",
    "last_name": null,
    "group_type": false,
    "id": "xenblda7vh6l6qrs679",
    "parent": [],
    "access": false,
    "plans": null
  }
}

add plan

Endpoint: /api/customer/add_plan

Add a plan based on a known plan number. Currently we don't accept payment method details via the API. When the payment method is set to card the customer is prompted to activate their account with their payment details.

customer_id Customer's id returned in get or create requests (required)
plan_number A known plan number (required)
plan_type Default: 1 (optional)
1 == subscription, 2 == subscription trial
payment_method Default: 1 (optional)
0 == None, 1 == Card, 2 == Invoice or bill to pay later
send_notice Default: TRUE (optional)
If true then the order notice is sent. If false, then it's not sent.

POST example (before url encoding)

POST /api/customer/add_plan?client_id=your_client_id&api_key=your_secret_api_key&data={"customer_id":"xenblda7vh6l6qrs679","plan_number":"12345","plan_type":1,"payment_method":1}

POST example (url encoded)

POST /api/customer/add_plan?client_id=your_client_id&api_key=your_secret_api_key&data=%7B%22customer_id%22%3A%22xenblda7vh6l6qrs679%22%2C%22plan_number%22%3A%2212345%22%2C%22plan_type%22%3A1%2C%22payment_method%22%3A1%7D

 

JSON Response

{
  "success": true,
  "customer": {
    "email": "nick@sabramedia.com",
    "display_name": "Nick Johnson",
    "sex": "",
    "dob": "",
    "first_name": "Nick",
    "last_name": "Johnson",
    "group_type": false,
    "id": "6e4a8f33oreg8jd0ln1",
    "parent": [],
    "access": true,
    "plans": [
      {
        "access_id": 3,
        "access_tag": "default",
        "name": "Print + Digital Bundle Monthly $7.00 subscription",
        "start": "2018-05-01",
        "type": 1
      }
    ]
  }
}

Plan

Coming soon.