Search

Magnify Partner API Documentation

Magnify Partner API Documentation

This API provides programmatic access to various resources produced by the Magnify platform. Access is restricted to resources that the authenticated client has permission to view. Authentication is done via OAuth 2.0 client credentials.

Base URL: https://api.magnify.io/v1/partner
Version: 1.0.0
Contact: support@magnify.io

Authentication

The Magnify Partner API uses OAuth 2.0 client credentials flow for authentication. All API requests must include a valid JWT access token in the Authorization header.

Getting an Access Token

To obtain an access token, make a POST request to the token endpoint: 

curl -X POST https://auth.magnify.io/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=partner-api/motions.read"

Request Parameters

Parameter Type Required Description
grant_type string Yes Must be client_credentials
client_id string Yes Your OAuth 2.0 client identifier
client_secret string Yes Your OAuth 2.0 client secret
scope string Yes Space-separated list of requested scopes

Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6Ikp...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Using the Access Token

Include the access token in the Authorization header of all API requests: 

curl -X GET https://api.magnify.io/v1/partner/motions/{motionId}/email-metrics \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Token Expiration

Access tokens expire after 1 hour (3600 seconds). When a token expires, you'll receive a 401 Unauthorized response. You must obtain a new token using the same client credentials flow.

Available Scopes

  • partner-api/motions.read - Access to read motion data

Endpoints

Get Motions

GET/motions

Retrieves a paginated list of motions. Results can be filtered by motion state.

Required Scope

partner-api/motions.read

Query Parameters

Parameter Type Required Description
size integer No Number of results to return per page
Min: 1, Max: 1000, Default: 10
from integer No Starting index for pagination (zero-based)
Min: 0, Max: 100, Default: 0
state string No Filter motions by their current state
Valid values: COMPLETED, DRAFT, EXECUTING, SCHEDULED, FAILED, ARCHIVED, CANCELLED

Example Request

curl -X GET "https://api.magnify.io/v1/partner/motions?size=10&from=0&state=COMPLETED" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Responses

200Success

Successfully retrieved motions

{
  "total": 5,
  "data": [
    {
      "id": "motion_00000000-0000-0000-0000-000000000000",
      "name": "Welcome Series",
      "version": 1,
      "createdAt": 1640995200000,
      "createdBy": "user_123",
      "state": "COMPLETED"
    },
    {
      "id": "motion_11111111-1111-1111-1111-111111111111",
      "name": "Onboarding Campaign",
      "version": 2,
      "createdAt": 1640995300000,
      "createdBy": "user_456",
      "state": "EXECUTING"
    }
  ]
}
400Bad Request

Validation failed

{
  "type": "/errors/motions",
  "message": "Failed to fetch motions - validation failed",
  "detail": "Invalid query parameters provided",
  "status": 400,
  "instance": "/v1/partner/motions",
  "validationErrors": [
    "size: should be = 1",
    "state: must be equal to one of the allowed values"
  ]
}
401Unauthorized

Invalid or missing OAuth 2.0 token

403Forbidden

Insufficient OAuth 2.0 scopes

429Too Many Requests

Rate limit exceeded

500Internal Server Error

An unknown error occurred on the server

Get Motion by ID

GET/motions/{motionId}

Retrieves a specific motion by its unique identifier.

Required Scope

partner-api/motions.read

Path Parameters

Parameter Type Required Description
motionId string Yes The unique identifier of the motion (UUID format)
Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
Example: 00000000-0000-0000-0000-000000000000

Example Request

curl -X GET "https://api.magnify.io/v1/partner/motions/00000000-0000-0000-0000-000000000000" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Responses

200Success

Successfully retrieved motion

{
  "id": "motion_00000000-0000-0000-0000-000000000000",
  "name": "Welcome Series",
  "version": 1,
  "createdAt": 1640995200000,
  "createdBy": "user_123",
  "state": "COMPLETED"
}
400Bad Request

Validation failed

{
  "type": "/errors/motions",
  "message": "Failed to fetch motion - validation failed",
  "detail": "Invalid motion ID format",
  "status": 400,
  "instance": "/v1/partner/motions/motion_123",
  "validationErrors": [
    "motionId: should match pattern \"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$\""
  ]
}
401Unauthorized

Invalid or missing OAuth 2.0 token

403Forbidden

Insufficient OAuth 2.0 scopes

404Not Found

Motion not found

429Too Many Requests

Rate limit exceeded

500Internal Server Error

An unknown error occurred on the server

Get Email Metrics for a Motion

GET/motions/{motionId}/email-metrics

Retrieves email-related metrics for a specific motion if they have used the Magnify Send Email action. This endpoint supports pagination.

Required Scope

partner-api/motions.read

Path Parameters

Parameter Type Required Description
motionId string Yes The unique identifier of the motion (UUID format)
Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
Example: 00000000-0000-0000-0000-000000000000

Query Parameters

Parameter Type Required Description
from integer No Starting index for pagination (zero-based)
Min: 0, Max: 99900, Default: 0
size integer No Number of results to return per page
Min: 1, Max: 100, Default: 10

Example Request

curl -X GET "https://api.magnify.io/v1/partner/motions/00000000-0000-0000-0000-000000000000/email-metrics?from=0&size=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Responses

200Success

Successfully retrieved motion email metrics

{
  "total": 25,
  "data": [
    {
      "account": {
        "id": "acc_123456789",
        "name": "Acme Corporation"
      },
      "user": {
        "id": "user_987654321",
        "name": "John Doe"
      },
      "motion": {
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "Welcome Series",
        "version": "1"
      },
      "emailEvent": {
        "templateId": "template_abc123",
        "templateVersion": 1,
        "type": "magnify_send_email_delivered"
      },
      "occurredAt": 1640995200000
    }
  ]
}
400Bad Request

Validation failed

{
  "type": "/errors/motions",
  "message": "Failed to fetch motion email metrics - validation failed",
  "detail": "A required parameter was missing from the request",
  "status": 400,
  "instance": "/v1/partner/motions/motion_123/email-metrics",
  "validationErrors": [
    "motionId: should be string"
  ]
}
401Unauthorized

Invalid or missing OAuth 2.0 token

403Forbidden

Insufficient OAuth 2.0 scopes or motion access denied

404Not Found

Motion not found or no email metrics available

429Too Many Requests

Rate limit exceeded

500Internal Server Error

An unknown error occurred on the server

Data Models

MotionsResponse

Field Type Description
total integer Total number of motions available
data array[MotionData] Array of motion data

MotionResponse / MotionData

Field Type Description
id string Unique identifier for the motion
name string Display name of the motion
version integer Version number of the motion
createdAt integer Timestamp when the motion was created (milliseconds since epoch)
createdBy string User ID who created the motion
state string Current state of the motion. Valid values: COMPLETED, DRAFT, EXECUTING, SCHEDULED, FAILED, ARCHIVED, CANCELLED

MotionEmailMetricsResponse

Field Type Description
total integer Total number of email metrics available
data array[EmailMetricDataPoint] Array of email metric data points

EmailMetricDataPoint

Field Type Description
account AccountInfo Account information
user UserInfo User information
motion MotionInfo Motion information
emailEvent EmailEventInfo Email event details
occurredAt integer Timestamp when the email event occurred (milliseconds since epoch)

Email Event Types

The emailEvent.type field can have the following values:

  • magnify_send_email_processed - Email has been processed and is ready to be sent
  • magnify_send_email_deferred - Email has been temporarily deferred due to issues like temporary failures or rate limiting
  • magnify_send_email_delivered - Email has been successfully delivered to the recipient's mail server
  • magnify_send_email_open - Email has been opened by the recipient
  • magnify_send_email_click - A link in the email has been clicked by the recipient
  • magnify_send_email_bounce - Email could not be delivered and was returned to sender
  • magnify_send_email_dropped - Email was dropped and not delivered (e.g., due to spam filtering, invalid recipient, or other delivery issues)
  • magnify_send_email_spamreport - Recipient marked the email as spam
  • magnify_send_email_unsubscribe - Recipient unsubscribed from emails
  • magnify_send_email_group_unsubscribe - Recipient unsubscribed from a specific group
  • magnify_send_email_group_resubscribe - Recipient resubscribed to a previously unsubscribed group

Error Response Format

All error responses follow this format:

{
  "type": "string",           // Error type identifier
  "message": "string",        // Human-readable error message
  "detail": "string",         // Detailed error description
  "status": 0,               // HTTP status code
  "instance": "string",       // The request URI that caused the error
  "validationErrors": []      // Array of validation errors (only for 400 errors)
}
Important Notes:
  • All timestamps are in milliseconds since epoch
  • The motionId must be a valid UUID
  • Pagination is zero-based (first item is at index 0)
  • Maximum page size is 100 items
  • Access tokens expire after 1 hour

Updated