Accounts REST API

The Accounts REST API enables developers to interact with your website via third-party applications or external data sources.

Learn more about REST APIs.

The following actions can be done with the accounts REST API.

All requests are submitted to /api/v1/account/accounts and it's the type of request that determines the action that is performed.

  • GET - retrieve one or more accounts
  • POST - add an account
  • PUT - fully edit an account
  • PATCH - partially edit an account
  • DELETE - delete an account

Retrieve one or more accounts

Retrieve a list of accounts that supports paging and filtering using a GET request.

Request type

GET

Request URL

/api/v1/account/accounts

Full request

curl -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' 'http://www.mysite.com/api/v1/account/accounts'

Response

Status: 200 OK

{
    "data": [
        {
            "id": 9,
            "email": "string",
            "username": "string",
            "firstName": "string",
            "middleName": "string",
            "lastName": "string",
            "displayName": "string",
            "company": "string",
            "title": "string",
            "department": "string",
            "website": "string",
            "phoneHome": "string",
            "phoneOffice": "string",
            "phoneMobile": "string",
            "phoneTollFree": "string",
            "phoneOther": "string",
            "pager": "string",
            "fax": "string",
            "gender": "unknown"
        },
        {
            ...other accounts....
        }
    ],
    "pagination": {
        "currentPage": 1, 
        "perPage": 6,
        "count": 6,
        "totalPages": 312,
        "total": 1867,
        "links": {
            "next": "?page=2&limit=6&sort=-lastName"
        }
    },
    "totalItems": 1867
}

Learn more about pagination within the REST API.

Parameters

Get more information about the common REST parameters.

Parameter Description
attributes

One or more attributes to filter the results by. Essentially this will search for items that have values that match the passed value for each attribute. Learn more

limit

The maximum number of items to retrieve. Learn more

page

The pagination page number to retrieve results for. Learn more

sort

Sets how to sort the results. Learn more

Retrieve a specific account

Retrieve a single account identified by it's id using a GET request. In this example we're getting the account whose id is 13. The difference between this request and getting multiple accounts is that the id of the account is specified at the end of the URL.

Request type

GET

Request URL

/api/v1/account/accounts/13

Full request

curl -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' 'http://www.mysite.com/api/v1/account/accounts/13'

Response

{
    "id": 13,
    "email": "string",
    "username": "string",
    "firstName": "string",
    "middleName": "string",
    "lastName": "string",
    "displayName": "string",
    "company": "string",
    "title": "string",
    "department": "string",
    "website": "string",
    "phoneHome": "string",
    "phoneOffice": "string",
    "phoneMobile": "string",
    "phoneTollFree": "string",
    "phoneOther": "string",
    "pager": "string",
    "fax": "string",
    "gender": "unknown"
}

 Add a new account

Create a new account using a POST request. The data of the request should be a JSON object containing the attribute values for the account. Each key is the attribute layout key and the value is the attribute value to save with the account. Below is an example of the JSON data.

{
    "email": "email@company.com",
    "username": "myusername",
    "firstName": "Bob",
    "middleName": "B",
    "lastName": "Smith",
    "company": "Acme Inc",
    "title": "Tester",
    "department": "Product Testing",
    "website": "http://www.acme.com",
    "phoneOffice": "111-222-3333",
    "phoneMobile": "222-333-4444",
    "gender": "male"
}

Accounts are unique in that there are no attributes that are required because you could be adding accounts for a variety of reasons. However, reasonable minimum attribute values include:

  • email
  • username
  • password
  • firstName
  • lastName

You can also include any custom attributes the same way as you would the default attributes.

Request type

POST

Request URL

/api/v1/account/accounts

Full request

curl -X POST -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' -d '{"email": "email@company.com","username": "myusername","firstName": "Bob","middleName": "B","lastName": "Smith","company": "Acme Inc","title": "Tester","department": "Product Testing","website": "http://www.acme.com","phoneOffice": "111-222-3333","phoneMobile": "222-333-4444","gender": "male"}'  'http://www.mysite.com/api/v1/account/accounts'

Response

The response would be the full account information including it's id.

{
    "id": 27,
    "email": "email@company.com",
    "username": "myusername",
    "firstName": "Bob",
    "middleName": "B",
    "lastName": "Smith",
    "company": "Acme Inc",
    "title": "Tester",
    "department": "Product Testing",
    "website": "http://www.acme.com",
    "phoneOffice": "111-222-3333",
    "phoneMobile": "222-333-4444",
    "gender": "male"
    "links": [
        {
            "rel": "self",
            "url": "/accounts/2758"
        }
    ]
}

Edit an account

To fully edit an account you would submit a PUT request. The attributes values that you submit will be updated on the account. If any attributes are not submitted, then their values will be cleared out.

The request URL will include the id of the account to edit at the end of the URL.

In this example we're going to edit an account with an id of 27.

Request type

PUT

Request URL

/api/v1/account/accounts/27

Full request

curl -X PUT -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' -d '{"email": "email@company.com","username": "myusername","firstName": "Bob","middleName": "B","lastName": "Smith","company": "Acme Inc","title": "Tester","department": "Product Testing","website": "http://www.acme.com","phoneOffice": "111-222-3333","phoneMobile": "222-333-4444","gender": "male"}'  'http://www.mysite.com/api/v1/account/accounts/27'

Response

The response would be the full account information including it's id.

{
    "id": 27,
    "email": "email@company.com",
    "username": "myusername",
    "firstName": "Bob",
    "middleName": "B",
    "lastName": "Smith",
    "company": "Acme Inc",
    "title": "Tester",
    "department": "Product Testing",
    "website": "http://www.acme.com",
    "phoneOffice": "111-222-3333",
    "phoneMobile": "222-333-4444",
    "gender": "male"
    "links": [
        {
            "rel": "self",
            "url": "/accounts/2758"
        }
    ]
}

Partially edit an account

To partially edit an account you would submit a PATCH request. Only the attribute values that are submitted will be updated on the account. All other existing attribute values will be left unchanged.

In this example we're going to partially edit an account with an id of 27.

Request type

PATCH

Request URL

/api/v1/account/accounts/27

Full request

curl -X PATCH -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' -d '{"email": "email@company.com","username": "myusername"}'  'http://www.mysite.com/api/v1/account/accounts/27'

Response

The response would be the full account information including it's id.

{
    "id": 27,
    "email": "email@company.com",
    "username": "myusername",
    "firstName": "Bob",
    "middleName": "B",
    "lastName": "Smith",
    "company": "Acme Inc",
    "title": "Tester",
    "department": "Product Testing",
    "website": "http://www.acme.com",
    "phoneOffice": "111-222-3333",
    "phoneMobile": "222-333-4444",
    "gender": "male"
    "links": [
        {
            "rel": "self",
            "url": "/accounts/2758"
        }
    ]
}

Delete an account

To delete an account you would submit a DELETE request. No response is returned if the deletion is successful. A HTTP status code of 204 is returned.

In this example, we're going to delete an account with an id of 27.

Request type

DELETE

Request URL

/api/v1/account/accounts/27

Full request

curl -X DELETE -H 'Accept: application/json' -H 'Authorization:Bearer 755E52F29EEBD511BEF73646C1E911401084E7A9' 'http://www.mysite.com/api/v1/account/accounts/27'

Response

The response body will be empty. No JSON is returned. Rather, the response HTTP status code will be 204 if the deletion was successful.