This documentation page describes the API protocol that is available for grouped accounts, for the management of accounts within the group. Grouped accounts are a special feature reserved for large or enterprise accounts.
Individual accounts within a multi-account system can all be managed with a single API key, as long as that key is created from the "Global administrators" page within the "manage accounts" menu.
When using such a key, it is used exactly the same as a normal API key, except that an additional parameter
needs to be provided to specify the account that the action is for. This parameter is account_id
and is added as a query parameter. The Account ID for each account is shown in the "manage accounts" menu.
Users can be managed for a single account using a global API key in the same way as all other objects, by specifying the account_id.
If the account ID is not specified, then global users will be assumed instead.
The following example shows how to retrieve contacts for an account:
curl https://dev.simplelists.com/api/2/contacts/?account_id=20 -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE:
The following example shows how to retrieve users for an account:
curl https://dev.simplelists.com/api/2/users/?account_id=20 -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE:
The following example shows how to retrieve global users:
curl https://dev.simplelists.com/api/2/users/ -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE:
This section details the additional objects that are available for multi-account systems, along with the possible actions and the parameters that should be sent.
The account object is used for managing accounts within a group of accounts.
| id | Simplelists identifier for the account |
|---|---|
| description | A free text description to identify the account |
| administrator | The initial administrator of the account |
| lists | An array of lists in the account (read requests only) |
| users | An array of standard users in the account (read requests only). Each user is
returned as an API user object, but with only the keys id and username |
The following additional parameters are available when reading or writing a single account:
| confirmation_message | The confirmation message used as the email body for subscription and confirmation requests. |
|---|---|
| confirmation_subject | The subject line of confirmation emails used for subscription and confirmation requests. |
| welcome_message | Custom message displayed to the user once they confirm their email address. |
| send_welcome_message_confirmation | Boolean value indicating whether the welcome message should be emailed to a member when they confirm their email address. |
| send_welcome_message_contacts | Boolean value indicating whether the welcome message should be emailed to a contact as soon as they are added to the account. |
| timezone | Timezone of the account. |
| custom_image | URL of a custom image to use for the account. |
| notify_approval | Setting for sending approval notification emails:
|
| subscriptions | Whether subscriptions are enabled by default on this account (can be overridden per list). Set to “open” (enabled), “open+confirm” (enabled with approval by list owner) or “closed” (not enabled). |
| unsubscriptions | Whether unsubscriptions are enabled by default on this account (can be overridden per list). Set to “open” (enabled), “open+confirm” (enabled with approval by list owner) or “closed” (not enabled). |
| list_delegation | Boolean value indicating whether list owners can delegate access to their lists to new and existing administrators. |
| restrict_contact | Array of regular expressions that will be used to check any email address added to the account. Any email address not matching one or more of these patterns will be rejected. |
| restrict_contact_subscription | Array of regular expressions that will be used to check any email address of a subscription request. Any email address not matching one or more of these patterns will be rejected. |
| require_list_approval | Boolean value indicating whether new lists need to be approved. |
Use a GET request to retrieve a single account using a Simplelists identifier.
| Method: | GET |
|---|---|
| URI: | https://dev.simplelists.com/api/2/accounts/:id/ (where :id is a Simplelists account identifier) |
| Query parameters: | Optionally use the following URL parameters:
|
| Response: | A JSON object containing a single account object |
| Example: | curl https://dev.simplelists.com/api/2/accounts/24/ -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE: |
Use a GET request to retrieve all accounts.
| Method: | GET |
|---|---|
| URI: | https://dev.simplelists.com/api/2/accounts/ |
| Query parameters: | None |
| Response: | A JSON list containing account objects |
| Example: | curl https://dev.simplelists.com/api/2/accounts/ -u CAJgeo1bepNW2bpQWPDlrnhT8hwOAZCE: |
Use a POST request to create an account.
| Method: | POST |
|---|---|
| URI: | https://dev.simplelists.com/api/2/accounts/ |
| Body parameters: | Use the parameters of an account object in the body of the request. |
| Response: | A JSON object containing the created account |
| Example: | curl https://dev.simplelists.com/api/2/accounts/ \ |
Use a PUT request to update a single account object.
| Method: | PUT |
|---|---|
| URI: | https://dev.simplelists.com/api/2/accounts/:id/ (where :id is a Simplelists account identifier) |
| Body parameters: | Add all or any of an account object's properties to the body of the request to update them |
| Response: | A JSON object containing the updated account object |
| Example: | curl https://dev.simplelists.com/api/2/accounts/:id/ \ |
Use a DELETE request to delete a single account.
| Method: | DELETE |
|---|---|
| URI: | https://dev.simplelists.com/api/2/accounts/:id/ (where :id is a Simplelists account identifier) |
| Parameters: | None |
| Response: | A JSON success message |
| Example: | curl -X DELETE https://dev.simplelists.com/api/2/accounts/26/ \ |
