Getting Started with the SMAC CRM API 2.0

SMAC CRM API 2.0 allows you to sync email activity and campaign stats with your database, manage lists/audiences, view and control Automation workflows, and test calls and endpoints before pushing to production.

Resources

Resources are typically nouns like, subscribers or campaigns, that you take actions on using supported HTTP verbs. The root directory for the API includes a map of all available resources and their

subresources:

https://<dc>.api.smaccrm.com/2.0

The <dc> part of the URL corresponds to the data center for your account. For example, if the last part of your SMAC CRM API key is us6, all API endpoints for your account are available at https://us6.api.smaccrm.com/2.0.

Each resource is typically separated into a resource/{id} format, with subresources following the same pattern.

For example, if you are looking for information about lists/audiences, make a GET request to https://<dc>.api.api.smaccrm.com/2.0/lists. To access an individual list, make a GET request to https://<dc>.api.smaccrm.com/2.0/lists/{list_id}.

curl --request GET \
--url 'https://<dc>.api.smaccrm.com/3.0/' \
--user 'anystring:<your_apikey>'

User Roles

Access to each endpoint is determined by the role of the user who generated the API key. To learn more about user level permissions, see Manage User Levels in Your Account.

If a user cannot access an endpoint, the request will receive a 403 error.

You can check a user’s role using the API Root endpoint.

HTTP Methods

The SMAC CRM API supports 5 HTTP methods for interacting with resources:

Actions

In some places in the SMAC CRM API, we need to deviate from traditional REST guidelines. Completely removing verbs isn’t possible for every type of request, like pausing an Automation workflow. To pause an Automation workflow, you make a POST request to /automations/{workflow_id}/emails/{id}/actions/pause, but all action endpoints are namespaced this way.

When we talk about supported methods in the API Reference, we refer to these endpoints differently. Any endpoint that uses actions is prefixed with an ACTION label instead of a CREATE label, and displays under the Actions tab instead of the Create tab.

Secure Requests

We give a valid, signed certificate for all API methods. If you are manually coding submit URLs, change http to https in the URL, and make sure the connection library supports HTTPS.

JSON

The SMAC CRM API only supports JSON. So instead of XML, HTTP POST parameters, or other serialization formats, most POST and PATCH requests require a valid JSON object for the body. The API Reference includes complete examples, but here’s a quick look at the JSON format we are looking for in POST and PATCH requests:

Parameters

There are four main categories of parameters for each endpoint in the SMAC CRM API: path, query string, request body, and response body. The API Reference includes a list of all available parameters for each possible request, but these sections offer an overview of the main categories and subcategories.

Path parameters

In an API URL, resource names and unique identifiers help you figure out how to structure your requests. Resource names are immutable, but resource identifiers are required, so you need to replace them with real values from your SMAC CRM account. Let’s look at an example:

https://crm.smacsoftwares.de:9030/api/v1/api/v1/

In that URL, there is one primary resource, lists, and two subresources: members, and notes. There are also three different path parameters that you need to replace with real values from your SMAC CRM account: list_id, email_id, and id. When you replace those values with actual data, your final URL should look something like this:

https://crm.smacsoftwares.de:9030/api/v1/api/v1/

Query string parameters

We use query string parameters for filtering, pagination, and partial responses in the SMAC CRM API. The format for query string parameters is the full resource URL followed by a question mark, and the optional parameters:

https://crm.smacsoftwares.de:9030/api/v1/api/v1/

Filtering

The API Reference shows you which resources you can filter on, and what to include in your URL query string. For example, to view only RSS campaigns, use

If you provide multiple filters, we only return resources that match all filters.

Pagination

Paginate your API requests to limit response results and make them easier to work with. We use offset and count in the URL query string to paginate because it provides greater control over how you view your data.

The maximum value for Count is 1000.

Offset defaults to 0, so if you use offset=1, you will miss the first element in the dataset. Count defaults to 10. For example, this URL includes query string parameters for pagination:

https://crm.smacsoftwares.de:9030/api/v1/api/v1/

Request body parameters

For PATCH, PUT, and POST requests, you may need to include a request body in JSON format. The API Reference shows you all the available request parameters for each endpoint, including required fields. The following example shows you how to create a new list/audience with an HTTP POST request using curl (note the format of the --data option).

curl --request POST \
--url 'https://crm.smacsoftwares.de:9030/api/v1/api/v1/
--user 'anystring:apikey' \
--header 'content-type: application/json' \
--data '{"name":"Freddie'\''s Favorite Hats","contact":{"company":"SMAC CRM","address1":"675 Ponce De Leon Ave NE","address2":"Suite 5000","city":"Atlanta","state":"GA","zip":"30308","country":"US","phone":""},"permission_reminder":"You'\''re receiving this email because you signed up for updates about Freddie'\''s newest hats.","campaign_defaults":{"from_name":"Freddie","from_email":"freddie@freddiehats.com","subject":"","language":"en"},"email_type_option":true}' \
--include

Response body parameters

Every API call response includes headers and an optional JSON-formatted body.

The API Reference includes all possible response body parameters, but the following example shows the type of JSON-formatted response to expect from a POST request to the /lists endpoint:

Code Examples

Throughout the SMAC CRM API documentation, we include code examples so you know how to format your requests, and what kind of data to expect in return.

We use curl to show all requests. For example, the following code snippet shows a POST request to the /lists endpoint:

For most example requests, we use the same set of curl commands:

Errors

We expose API errors in two ways: standard HTTP response codes and human-readable messages in JSON format. For example, the following code snippet shows an HTTP 405 error in the response headers:

HTTP/1.1 405 Method Not Allowed
Server: nginx
Content-Type: application/problem+json; charset=utf-8
Content-Length: 253
X-Request-Id: a1efb240-f8d8-40fe-a680-c3a5619a42e9
Link: <https://us2.api.mailchimp.com/schema/3.0/ProblemDetailDocument.json>; rel="describedBy"
Date: Thu, 17 Sep 2015 19:02:28 GMT
Connection: keep-alive
Set-Cookie: _AVESTA_ENVIRONMENT=prod; path=/

And this snippet shows the human-readable error as a JSON object:

{"type":"https://developer.mailchimp.com/documentation/mailchimp/guides/error-glossary/#405","title":"Method Not Allowed","status":405,"detail":"The requested method and resource are not compatible. See the Allow header for this resource's available methods.","instance":""}

For HTTP response codes, 4xx codes suggest a bad request. If you receive a 4xx response, we recommend reviewing the error glossary for more context to help you troubleshoot. 5xx errors suggest a problem on SMAC CRM’s end, so if you receive a 5xx error, we recommend checking @SMACCRMStatus and @SMACCRM_API on Twitter to see if we are experiencing any system-wide issues.

Otherwise, contact our support team. If you contact support, we recommend including the complete request you are trying to make and the error code and response you are receiving so they can help as quickly as possible.

Throttling

To improve connections and experiences for all our users, we use some connection limits when we see suspicious activity or overload. Each user account is permitted up to 10 simultaneous connections, and you will receive an error message if you reach the limit. We do not throttle based on volume. Note: currently there are no options to raise that limit on a per-customer basis.

Response Format

To start, we recommend reviewing the errors section in this guide, and method-specific errors for the endpoint you are trying to access. If you are seeing a 5xx error, that likely means there is an error on SMAC CRM side, and you can contact our support team at support@smaccrm.com