Skip to Content
AI Powered Docs! 🤖 These docs are translated with AI, so keep an eye out for minor quirks. We're always improving!
Technical DocumentationRest APIGetting Started

REST API - Getting Started

This guide will help you send your first Server-to-Server (S2S) request to Metrix. By using the Metrix REST API, you can send data about your users and their behavior directly from your server to Metrix. This integration allows you to leverage Metrix’s analytical dashboards, user segmentation capabilities, and powerful Marketing Automation tools.

1. Obtaining Security Keys

To authenticate and successfully send data to Metrix, you need two security keys:

  • APP_ID (Application ID): This ID identifies your application in Metrix and is also used in SDK implementations.
  • API_Key (API Key): This key is specific to your Server-to-Server (S2S) integrations and is a confidential key for authenticating requests sent from your server to Metrix.

How to access the keys: Your APP_ID and API_Key are available in the Metrix dashboard, in the Application Settings section.

Important Note:

  • Keys are unique for each application. Make sure you are using the correct keys for your specific application.
  • Securing your API_Key is crucial. This is a server-type key, and it must not be used or exposed in client-side code (such as browser JavaScript or mobile clients). This key must be stored and used only on your server.

How to include the keys in the request header: After obtaining these keys, you must include them in the Header of every request you send to Metrix:

'X-Application-Id': '{YOUR APP_ID FROM METRIX DASHBOARD}'
'X-API-Key': '{YOUR API_Key FROM METRIX DASHBOARD}'

2. Data Submission Format and Endpoint

To send data to Metrix, you must send a POST request to the following address:

https://entry.metrix.ir/

Overall request structure:

Your request must include headers and a JSON-formatted body:

  • Header:

    • X-Application-Id: Your APP_ID
    • X-API-Key: Your API_Key
    • Content-Type: application/json

  • Body (JSON format): The request body includes the main fields for user identification and a list of messages:

{
  "customUserId": "username | email | phone | any unique user id", // e.g.: '+98912XXXXXXX'
  "metrixUserId": "<get id from sdk>", // device id obtained from sdk for attribution purposes
  "messages": [
    // Different message types (user, action, revenue, businessEvent) will be explained below
  ]
}

Explanation of main request body fields:

  • customUserId:

    • Purpose: A unique identifier to introduce the user to Metrix. This ID helps Metrix identify a unique user profile and track user behavior over time and across different devices.
    • Examples: It can be a username, email, phone number, or any other unique internal ID from your system.
    • Requirement: It is mandatory for Automation purposes and creating User Journeys. If you are also using an SDK, ensure the same value is set for each user.

  • metrixUserId:

    • Purpose: An ID that Metrix has assigned to the user’s device (Device ID).
    • How to obtain: This ID can be retrieved via the Metrix SDK in the mobile application or on the user’s website. For more details, refer to the relevant SDK documentation.
    • Requirement: It is mandatory for Attribution purposes and connecting events to the install source. If this ID is not sent, events will not be linked to the install source.

  • messages:

    • Purpose: A list (array) of messages, where each represents an event or an update about the user. In this list, you can send various message types (such as user, action, revenue, or business events).
    • General format for each message in the messages list:
{
  "type": "message type: user | action | revenue | businessEvent",
  "id": "request id", // random generated unique ID, e.g., a UUID. Example: "e9f0c1d2-a3b4-5c6d-e7f8-9a0b1c2d3e4f"
  "time": "event timestamp" // Unix timestamp in **seconds** as a **String**
  // ... other fields will vary depending on 'type'
}

Explanation of common message fields:

  • type:

    • This field specifies the type of message you are sending to Metrix. Allowed values include user (for user profile updates), action (for tracking user behavior), revenue (for tracking revenue), or businessEvent (for tracking system/business events). The other fields of each message will vary depending on its type.

  • id:

    • This field is used to detect and prevent duplicate message submissions. For each message in the messages list, you must generate a random and unique ID at the moment of creation (e.g., using a UUID). The format of this ID must be a String with no other restrictions.

  • time:

    • This field indicates the time the event occurred. Its format must be a Unix Timestamp in seconds and be a String.
    • Example: "1733830178" (for December 10, 2024, 10:09:38 PM UTC)

3. Important Considerations for User Identifiers

  • At least one of the customUserId or metrixUserId parameters must be specified. Without these identifiers, Metrix cannot correctly attribute events to users.
  • Automation: For using Metrix Automation capabilities (such as User Journeys and targeted messaging), providing customUserId is mandatory.
  • Attribution: For Attribution purposes (e.g., connecting in-app events to the app install source), providing metrixUserId is essential. If metrixUserId is not sent, events will not be linked to the install source.

For more information on user identifier types and their roles in Metrix, please refer to the Metrix Identifiers section.

4. Helper Tools

  • Postman Collection: To facilitate testing and sending requests, you can download the Postman Collection from here. This collection includes sample requests for sending user and action events.
Rest APITracking Users