MAGNETIQ API Reference
Build powerful consumer experiences with our comprehensive API
Introduction
The MAGNETIQ API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
You can use the MAGNETIQ API to access all the functionality available in our web interface programmatically, allowing you to build custom integrations and automate your workflows.
Base URL
https://api.magnetiq.com/v1
Authentication
The MAGNETIQ API uses API keys to authenticate requests. You can view and manage your API keys in the MAGNETIQ Dashboard.
Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.
Authentication Example
curl -X POST https://api.magnetiq.com/v1/auth/token \ -H "Content-Type: application/json" \ -d '{ "client_id": "your_client_id", "client_secret": "your_client_secret" }'
Rate Limits
The MAGNETIQ API implements rate limiting to protect our infrastructure and ensure fair usage. Rate limits are applied on a per-API key basis.
Plan | Rate Limit | Burst Limit |
---|---|---|
Free | 100 requests/hour | 20 requests/minute |
Pro | 1,000 requests/hour | 100 requests/minute |
Enterprise | 10,000 requests/hour | 500 requests/minute |
Errors
The MAGNETIQ API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided, and codes in the 5xx range indicate an error with MAGNETIQ& ;s servers.
Code | Description |
---|---|
200 - OK | Everything worked as expected. |
400 - Bad Request | The request was unacceptable, often due to missing a required parameter. |
401 - Unauthorized | No valid API key provided. |
403 - Forbidden | The API key doesn& ;t have permissions to perform the request. |
404 - Not Found | The requested resource doesn& ;t exist. |
429 - Too Many Requests | Too many requests hit the API too quickly. |
500 - Server Error | Something went wrong on MAGNETIQ& ;s end. |
Authentication Endpoints
/auth/token
Generate an authentication token
Example Request
curl -X POST https://api.magnetiq.com/v1/auth/token \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json"
/auth/refresh
Refresh an existing token
Example Request
curl -X POST https://api.magnetiq.com/v1/auth/refresh \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json"
Consumers Endpoints
/consumers
List all consumers
Example Request
curl -X GET https://api.magnetiq.com/v1/consumers \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json"
/consumers/{id}
Get a specific consumer
Example Request
curl -X GET https://api.magnetiq.com/v1/consumers/{id} \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json"
/consumers
Create a new consumer
Example Request
curl -X POST https://api.magnetiq.com/v1/consumers \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json"
Brands Endpoints
/brands
List all brands
Example Request
curl -X GET https://api.magnetiq.com/v1/brands \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json"
/brands/{id}
Get a specific brand
Example Request
curl -X GET https://api.magnetiq.com/v1/brands/{id} \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json"
/brands
Create a new brand
Example Request
curl -X POST https://api.magnetiq.com/v1/brands \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json"
Analytics Endpoints
/analytics/engagement
Get engagement metrics
Example Request
curl -X GET https://api.magnetiq.com/v1/analytics/engagement \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json"
/analytics/conversion
Get conversion metrics
Example Request
curl -X GET https://api.magnetiq.com/v1/analytics/conversion \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json"
Code Examples
Authentication Example
// Initialize the MAGNETIQ client with your API key const magnetiq = require('magnetiq-js')('YOUR_API_KEY'); // Generate an authentication token magnetiq.auth.createToken({ client_id: 'your_client_id', client_secret: 'your_client_secret' }) .then(response => { console.log('Authentication successful!'); console.log('Access token:', response.access_token); console.log('Expires in:', response.expires_in, 'seconds'); }) .catch(error => { console.error('Authentication failed:', error.message); });
Fetching Consumers Example
// Initialize the MAGNETIQ client with your API key const magnetiq = require('magnetiq-js')('YOUR_API_KEY'); // List consumers with pagination and filtering magnetiq.consumers.list({ limit: 10, page: 1, filter: { segment: 'high_value', created_after: '2023-01-01' } }) .then(response => { console.log('Total consumers:', response.total); console.log('Consumers:', response.data); }) .catch(error => { console.error('Failed to fetch consumers:', error.message); });