Skip to main content

Use REST API

Updated

REST API provides a modern, industry-standard REST API for retrieving and updating records in SmartSimple, with interactive Swagger documentation. Each request returns only the records permitted by the business security configuration and permissions of the associated API user.

Who: Global administrators

When to Use REST API

Use REST API when:

  • Building a connection between SmartSimple and a third-party system, such as a payment processor, that creates or updates records directly in SmartSimple.
  • Importing payment records into SmartSimple from third-party accounting software on a recurring basis.
  • Retrieving records from SmartSimple. For example, to display SmartSimple data in a reporting or BI tool.
  • Creating or uploading records in SmartSimple. For example, a payment processor or accounting system posting payment records, or an HR platform pushing employee record changes. 

↑ Back to top

Create a User with API Access

To create a user with API access:

  1. Create a new user following the steps outlined in Manage Users and Contacts.
  2. From the new user's record, click the Actions drop-down menu and select Edit Roles and Access.
  3. Locate the Access Type field and click API Access, and then click Save.

↑ Back to top

Create a New User Access Token

To create a new user Access Token for REST API:

NOTE   Before continuing with these steps, confirm that a user with API access exists. If not, follow the steps in Create a User with API Access.
  1. Click the System Administration gear in the upper navigation bar, select Global Settings from the drop-down menu, and then click the Integrations tab.
  2. Locate the API Settings section and click API Users.API users
     
  3. Click the edit [pencil] icon next to the applicable user.
  4. Click User Access Tokens in the left navigation.User Access Tokens
     
  5. Click the Generate User Access Token [+] button.
  6. Click the Note and Expiration fields and enter the applicable information.note and expiration fields' width=
     
  7. Locate the Token Type field and click SmartSimple REST API.token type field
     
  8. Complete the fields and then click Save.Save

↑ Back to top

View External API Explorer

The External API Explorer, or Swagger page, stores all the documentation and allows you to log in and test your API calls to the endpoint.

NOTE   Documentation and endpoints are only visible after logging into SmartSimple as a global administrator. This prevents exposing site-specific details, such as internal IDs, to unauthenticated users.

To use the Access Token to view the SmartSimple External API:

  1. Click the System Administration gear in the upper navigation bar, select Global Settings from the drop-down menu, and then click the Integrations tab.
  2. Locate the API Settings section and click External API Explorer.external API explorer
     
  3. Click API User Token.API user token
     
  4. Click the Value field, paste the token from the Create a New User Access Token section, and then click Save.value and save
     

You can now build a JSON and test the endpoints in the Swagger page.

NOTE   The records returned reflect the token's scope and, if enabled, the associated user's permissions. See Create a New User Access Token.

↑ Back to top

Access REST API Filter Builder

The REST API Filter Builder is for the search endpoints, for example, querying or searching records based on specific criteria or filter conditions.

To access the SmartSimple REST API Filter Builder:

  1. Click the System Administration gear in the upper navigation bar, select Global Settings from the drop-down menu, and then click the Integrations tab.
  2. Locate the API Settings section and click SmartSimple REST API Filter Builder.SmartSimple REST API Filter Builder
     
  3. Enter the applicable filters and click Generate JSON.generate JSON
     
  4. Click Copy to Clipboard and test it out in the Swagger page shown in the View External API Explorer section.copy to clipboard

↑ Back to top

Helpful Links