Accounts REST API
The Accounts REST API enables developers to interact with your website via third-party applications or external data sources.
The following actions can be done with the accounts REST API.
- Retrieve one or more accounts
- Retrieve a single account
- Add a new account
- Edit an account
- Partially edit an account
- Delete an account
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:
- 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.