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

POST/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"

POST/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

GET/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"

GET/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"

POST/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

GET/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"

GET/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"

POST/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

GET/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"

GET/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);
});