Concepts
These concepts are commonly used throughout the Rhythm API. They are useful to understand before exploring guides or references for specific APIs.
Tokens
Rhythm's API will accept either tokens generated for a specific user (user access tokens), or a token generated for automated machine-to-machine scripts (M2M access tokens).
There is a monthly limit on the number of M2M access tokens you may generate across all your integrations (1,000). If you exceed this limit, you will not be able to issue any M2M tokens until the next month, which may cause your integrations to fail.
Tokens are valid for 24 hours, so they should be securely cached and reused during that period to reduce consumption. When properly cached, each application using the Rhythm API should only be using a maximum of 31 M2M access tokens per month.
This limit does not apply to the other authorization flows where a user is interactively entering credentials (see below). You should never create a new M2M access token for each user login.
Because of the limit on M2M tokens, you should instead use a user access token whenever you are accessing the Rhythm API on behalf of a user who has logged in interactively. If a user is asked to enter their credentials, you should use the Authorization Code flow whenever possible.
If your application cannot support redirecting the user and must receive user credentials directly, you may instead use the Resource Owner Password flow to generate a user access token using an API call.
In this case, please reach out to Rhythm by creating a support request in ZenDesk so this option can be enabled for your API credentials.
M2M access tokens are only appropriate for scenarios where no interactive user is logged in, such as automated, recurring jobs, or bulk data operations. Because API calls are being executed by a system with no interactive user, you should be able to securely cache and reuse a single M2M token for 24 hours.
For more information see the section on authentication.
Users vs. Contacts
A User and a Contact are distinct but related records. A Contact exists in the Rolodex (Contacts & Organizations) app and contains all demographic information. When a member joins, renews, registers, pays, or otherwise interacts with the Rhythm Portal, all of this information is related to their Contact record.
A User may be thought of as an identity, or as login credentials, that may come from a variety of systems external to Rhythm (Google, Facebook, LinkedIn, etc). A Contact record may be related to one or more Users.
One member may create multiple Users by logging in with LinkedIn, then Google, then Facebook, and link all of these Users to the same Contact.
Because all records in Rhythm are related to the Contact, when the member logs in to the Rhythm Portal, they will always see the same information regardless of which User account they use for authentication.
This User + Contact link is established the first time a User logs into the Rhythm Portal. The related Contact ID is added to the User metadata and can later be retrieved from any JSON Web Token (JWT) issued for the user. For more information see
authentication or SSO guide.
Requests
Most requests require a tenantId parameter passed in the URI. This value identifies the Rhythm tenant the API call is being executed against. If you do not know your tenantId, please log a support request in ZenDesk.
For multi-tenant integrations, you must supply the tenantId that is applicable for the current request.
Every request to the Rhythm API requires an HTTP Header called Authorization which is examined to allow or deny the request. In the authentication section, we will see how to retrieve an access token for a user to make API calls on their behalf.
If you submit a request for a tenantId the user is not authorized to access, or to a URI that does not match any endpoint, your request will be denied.
Many requests also require a contactId value passed in the URI. In most cases, this is the contactId for the user who initiated the API request, which you can extract from the authenticated user access token.
Responses
Most of the endpoints in the Rhythm API return a single record or item. However, some long-running tasks, such as queries will instead return an identifier that you can use to check the progress of the task. For an example, see the query guide.
Other tasks, such as processing an Order, Invoice, or Payment, will return an executionArn which can be used in the System API > Step Functions API to check on the status of these tasks.
Paging
When an endpoint may return many records or items, rather than just returning an array, it will return the results in an Items attribute along with Count and LastEvaluatedKey attributes. The LastEvaluatedKey can be returned to the same endpoint using the exclusiveStartKey query string parameter to get the next page of results.
Looping through a large number of pages programmatically may cause you to exceed API rate limits.
Instead, use a query to retrieve all items at once as described below.
Retrieving Multiple Items
The Rhythm API uses three patterns for retrieving multiple items in a single request & response.
| Capability | List | Search | Query |
|---|---|---|---|
| Specify return fields | Yes | Yes | Yes |
| Paged results | Yes | Yes | No |
| Filter results | No | Yes | Yes |
| Complex criteria | No | No | Yes |
| Fields from related types | No | No | Yes |
| Multiple return formats | No | No | Yes |
List
The simplest are lists which are GET endpoints that return a simple JSON array of items. These endpoints do not have the option to supply custom criteria.
Examples of list endpoints might be listAddressTypes or getUpcomingEvents.
Like most GET endpoints, you can supply field names in the query string to limit the response size, which can be very useful for client-side javascript or mobile clients.
Search
A search is a strongly typed POST endpoint which defines preset criteria options you can supply in the body to change the search parameters. These endpoints return a JSON response which may contain Count, Items, and LastEvaluatedKey attributes. The Items attribute will be an array containing one page of the items that match all the criteria you supplied (see Paging above).
Examples of search endpoints might be searchForContacts or searchForEvents.
Query
A query uses multiple POST and GET endpoints. The same endpoints are used to initiate a query regardless of the type of record being returned. A query will return a JSON response with a signed URI where you can download a loosely typed dataset containing all the items that match the criteria.
Query is the most flexible method for retrieving multiple items. With a Query you can:
- Define criteria with advanced
anyorallgrouping, nested groups, and a variety of operators. - Return results in
json,csv,excel, or another data type you specify. - Use return and criteria fields from multiple types, or multiple apps, within the same query.
To learn more about queries see the Query Guide.
What's Next
Head over to the Authentication section to learn about the different authentication flows the Rhythm APIs support.