Upload API Data
Uploading data involves making a POST request to an Ambition endpoint.
Where do I find our custom credentials?
What information is needed for the POST request?
My POST request failed, and I received an error message.
What is "Sandbox Mode" and how do I enable/disable it?
Important to Note
There is a 15MB file size limit.
Either CSV or JSON formatted files can be uploaded, but a single integration cannot receive both formats.
- CVS file must be a flat file with headers
- JSON must either be flat (unnested) before transmission or flattened with the JSON Transformer within an Ambition API integration.
The file must contain the CSV headers or JSON keys that are included in the Data Format.
All data in Ambition must be attributable to a user. If your data exists at a team or organizational level, it must be broken down into user level metrics.
Locate API Credentials
1. Log in to your Ambition instance.
2. Open the left navigation and click Administration > Data > Integrations.
3. Click Edit in line with the appropriate API integration.
4. Click on Data Format to find your CONTENT_TYPE labeled as Data Format, CSV or JSON. Confirm the file set to be transmitted is formatted in the set data format.
Required field names for your file can be found here under the Data Format section labeled as Field Keys.
5. Click on Credentials to find your AUTH_TOKEN and ENDPOINT.
POST Request
You will need to construct a POST request consisting of three parts: Authorization Header, Content Type Header, and Body.
Authorization Header
Authorization: Token AUTH_TOKEN
Content Type Header
| CONTENT_TYPE | DATA_FORMAT | CONTENTS |
| application/json | JSON |
JSON Formatted Data |
| text/csv | CSV |
CSV Formatted Data |
| application/vns.ms-excel | CSV |
Excel Formatted Data |
Content-Type: CONTENT_TYPE
Body
The body will consist of either JSON or CSV data, dependent on selected DATA_FORMAT.
Refer to the "How do I construct data for an API integration?" for constructing the body's data.
Endpoint
Once constructed, you will send your POST request to the ENDPOINT found within the "Credentials" tab.
ENDPOINT, otherwise you will receive an error stating that the connection has been closed.If the POST is successful you will receive a 201 response code.
Example
Using cURL to upload
curl \
-H "Authorization: Token AUTH_TOKEN" \
-H "Content-Type: CONTENT_TYPE" \
-X POST \
-d '[{"email": "jason@yourcompany.com", "date": "8/16/2016", "calls": "3"}]' \
https://SUBDOMAIN.ambition.com/api/v1/data/DATA_TYPE/
Example Headers for using Postman to upload JSON
Errors
If a POST fails for any reason, all data contained within the request will be discarded.
For example, if you send 10 records and the 8th record is malformed and causes the request to fail, the 7 preceding records will be discarded.
If a request fails, the response will contain error messages consisting of IDs and Descriptions. Check both the response.status_code and response.content.
| ID | DESCRIPTION |
| import_parse_json | The JSON request body is improperly formatted. |
| import_parse_csv | The CSV request body is improperly formatted. |
| import_transform_data | The request body does not match the DATA_FORMAT. |
Sandbox Mode
What is Sandbox Mode and when should I use it?
Sandbox Mode is on by default when an API integration is first enabled in Ambition, and is notated by a "Sandbox Mode" badge in line with the integration on the Integration Management page.
Sandbox Mode allows for delivery of test and/or production files to an endpoint without impacting the instance as a whole. When an integration is in Sandbox Mode, the metrics created within the integration will not display outside of the integration and bad files will not halt processing.
Sending test files to an integration in "sandbox mode" is not a requirement, but is an optional capability meant to support organizations that would like to test file structures and data delivery methods. Sandbox Mode can be disabled or reenabled at any time.
Sandbox Mode is especially helpful when adding additional integrations to Ambition after you've launched to your end users.
What does Purging Data entail?
When in Sandbox Mode, you will have the option to purge the integration. Purging the integration entails all processed metric values and processed files will be deleted. Purging allows for any test and/or files with errors to be cleared out before production data is sent to Ambition.
Unless an integration is explicitly purged, any data from test files will contribute to metric values once Sandbox Mode is disabled.
Learn more about purging data here.
How do I disable/enable Sandbox mode?
1. Open the left navigation and click Administration > Data > Integrations.
2. Click Edit in line with the appropriate API integration.
Integrations currently in Sandbox Mode will feature a "Sandbox Mode" badge in line with the integration on the Integration Management page.
3. On the Settings page, locate the "Sandbox Mode" toggle
While in Sandbox mode, you will have the option to Purge All Data.
To Purge Data:
- Click the Purge All Data button.
- Click Confirm when prompted
To Disable Sandbox Mode:
- Toggle the Sandbox Mode option to Disabled.
- Click Save.
To Enable Sandbox Mode:
- Toggle the Sandbox Mode option to Enabled.
- Click Save.
Comments
0 comments
Please sign in to leave a comment.