Welcome to SWFI's RESTful API Documentation.
To authenticate, add an Authorization header to your API request that contains an API Key.
API Keys allow you to use another method of authentication separate from your account username and password. API Keys add an additional layer of security for your account because they limit access only to the API resources.
To use keys, you must set a plain text header named Authorization with the contents of the header being "XXX" where XXX is your API Secret Key.
To obtain an API Key, you will need an active SWFI account and can request them by contacting SWFI Support.
curl -v -X GET https://api.swfi.com/v1/entities \ -H "Accept: application/json" \ -H "Authorization: $API_KEY"
The host for API requests is https://api.swfi.com/v1.
All requests must be made over HTTPS. The API does not support HTTP.
You must provide an Authorization header as described in Authentication.
| Verb | Description |
|---|---|
| GET | Retrieve a resource or group of resources |
| POST | Create a new resource |
| PUT | Update an existing resource |
| DELETE | Delete an existing resource |
Version 1 of the SWFI API only allows for GET requests.
The API provides JSON responses. It doesn't currenly require the accept header but might in the future. If not set, the API will almost always use application/json.
Some resources offer direct file downloads and the "Content-Type" header should match the type of document.
curl -v -X GET https://api.swfi.com/v1/entities \ -H "Accept: application/json" \ -H "Authorization: $API_KEY"
When you send an array of data in a GET request, you will need to include the parameter multiple times on the URL. The parameter name does not require brackets.
The specific resource documentation will determine whether you are able to supply arrays of data as filters. Browse through the Collections to determine if you can supply arrays of data.
If the resource does not accept arrays of data, then the first supplied value will be used.
curl -v -X GET https://api.swfi.com/v1/entities?region=Asia®ion=Europe \ -H "Accept: application/json" \ -H "Authorization: $API_KEY"
Some GET resources allow for retrieval of information in batches. We will provide the query arguments in the resource documentation when available to consume.
When requesting multiple items, we will default the request limit to 10 items. You can specify a different limit but cannot exceed the maximum of 100.
Resources documented will display a bolded list of available paginated parameters if available.
| Parameter | Description |
|---|---|
| limit | The number of records to return |
| offset | The number of records to skip |
When using pagination, remember to keep your sort_field and sort_dir consistent. You are not required to supply a sort_field and sort_dir as each resource has defaults.
curl -v -X GET https://api.swfi.com/v1/transactions?limit=50&offset=250&sort_field=before_created_at=2022-09-01&sort_dir=ASC \ -H "Accept: application/json" \ -H "Authorization: $API_KEY"
All responses are returned in JSON format. We specify this by sending the Content-Type header.
Responses to a list retrieval or a lookup will include a JSON object payload where the "data" key includes the data requested. List retrievals will include the total_items key that can be used with Pagination.
API Documentationcurl -v -X GET https://api.swfi.com/v1/:resource \
-H "Accept: application/json" \
-H "Authorization: $API_KEY"
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": [{}, {}],
"total_items": integer
}curl -v -X GET https://api.swfi.com/v1/:resource/:_id \
-H "Accept: application/json" \
-H "Authorization: $API_KEY"
HTTP/1.1 200 OK
Content-Type: application/json
{
"data": {}
}Sometimes your API call will generate an error. Here you will find additional information about what to expect if you don't format your request properly, or we fail to properly process your request.
| Status Code | Description |
|---|---|
| 400 | Bad request |
| 401 | Requires authentication |
| 406 | Missing Accept header |
| 429 | Too many requests/Rate limit exceeded |
| 500 | Internal server error |
curl -v -X GET https://api.swfi.com/v1/:resource/:_id \
-H "Accept: application/json" \
-H "Authorization: $API_KEY"
HTTP/1.1 404 RESOURCE NOT FOUND
Content-Type: application/json
{
"errors": [
{
"path_parameter": "_id",
"message": "Not found"
}
],
"status": 404
}Below is a table containing descriptions of the various status codes we currently support against various resources.
| Status Code | Description |
|---|---|
| 200 | No error |
| 201 | Successfully created |
| 204 | Successfully deleted |
| 400 | Bad request |
| 401 | Require authentication |
| 404 | Not found |
| 406 | Missing Accept header |
| 429 | Too many requests/Rate limit exceeded |
| 500 | Internal server error |
All calls within the Web API are allotted a specific number of requests per refresh period. View the table below for the rate limits.
| Refresh Period | Rate |
|---|---|
| 10 minutes | 10 requests per second |
Once this threshold has been reached, we will return a 429 response code.
siege -v -b -c 40 -r 1 --header="Authorization: $API_KEY" https://api.swfi.com/v1/compass \ "GET https://api.swfi.com/v1/compass HTTP/1.1" 200 17567 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 200 17567 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 429 162 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 429 162 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 429 162 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 429 162 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 429 162 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 200 17567 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 200 17567 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 429 162 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 200 17567 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 429 162 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 429 162 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 429 162 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 429 162 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 429 162 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 429 162 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 429 162 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 429 162 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 429 162 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 429 162 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 200 17567 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 429 162 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 429 162 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 429 162 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 429 162 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 200 17567 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 429 162 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 429 162 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 429 162 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 429 162 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 429 162 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 429 162 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 429 162 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 200 17567 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 200 17567 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 200 17567 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 200 17567 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 200 17567 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7" "GET https://api.swfi.com/v1/compass HTTP/1.1" 200 17567 "-" "Mozilla/5.0 (pc-x86_64-linux-gnu) Siege/4.0.7"