> ## Documentation Index > Fetch the complete documentation index at: https://moengage-sdk-docs.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Track User > This API helps add or update users and user properties in MoEngage. **Use cases:** * Create a new user * Create new user property * Update existing user properties of users If you have [Portfolio](https://help.moengage.com/hc/en-us/articles/40394603054100-Portfolio) enabled for your workspace, you need to pass `project_code` in the API endpoint. This identifies which project a user or event belongs to. For more information, refer to [Portfolio: Data Ingestion and Management](https://help.moengage.com/hc/en-us/articles/40358246598804-Portfolio-Data-Ingestion-and-Management). **Array Support** If you want to pass an attribute in an array, the appropriate syntax for that is ```json "Array_attributeName":["abc","123"] ``` The sample cURL for adding and removing elements in an array is: ```json curl --location --request POST 'https://api-0X.moengage.com/v1/customer/{{appId}}?app_id={{appId}}'\ --header 'Content-Type: application/json' \ --header {"Authorization": "Basic Base64_ENCODED_APPKEY_APIKEY"} \ --data-raw '{ "type": "customer", "customer_id": "123", "attributes": { "removeValueFromArrayField": { }, "addValueToArrayField": { "attribute1":["abc","def"], "attribute2":["a"], "attribute3":["123"] }, "platforms" : [{"platform":"iOS", "active":"true"}] } }' ``` **Postman Collections** We have made it easy for you to test the APIs. Click [here](https://www.postman.com/moengage-dev/api-docs/collection/3182294-d7b7056d-9745-495d-bb61-7e3d87b64b39?action=share\&creator=3182294) to view it in Postman. **FAQs** * **How do we reduce the 5xx errors because of too many requests per second/minute?** Please attempt exponential backoff of requests to ensure there is no data loss due to 5xx errors. * **How do I know if my user data has been ingested into MoEngage?** Getting a 200 status code as a response from MoEngage only indicates that the users in your API payload have been accepted for processing. It does not ensure that the users sent to MoEngage have been successfully ingested. Although, this happens very rarely and you can search for newly ingested users in: `Segment > Create Segment > Search for users using their IDs` * **Can I use this API to also export users?** Please use the [Get User API](https://moengage.mintlify.app/api/user/get-user-details) to export the users. * **Can I use this API to delete users from MoEngage?** Please use the [Delete User API](https://moengage.mintlify.app/api/user/delete-users-in-bulk) to delete existing users in MoEngage. ## OpenAPI ````yaml /api/data/data.yaml post /customer/{app_id} openapi: 3.0.3 info: title: MoEngage Data APIs version: '1.0' description: >- This is a comprehensive OpenAPI specification for MoEngage's Data APIs, including User, Event, and Device management. It's designed to power an interactive API playground on your new documentation site. servers: - url: https://api-0{dc}.moengage.com/v1 description: MoEngage Core API Server variables: dc: default: '1' description: >- The ‘dc’ in the API Endpoint URL refers to the MoEngage Data Center (DC). MoEngage hosts each customer in a different DC. You can find your DC number and replace the value of ‘dc’ in the URL by referring to the DC and API endpoint mapping [here](https://help.moengage.com/hc/en-us/articles/360057030512-Data-Centers-in-MoEngage). Your MoEngage Data Center (DC) can be 1, 2, 3, 4,5, 6. enum: - '1' - '2' - '3' - '4' - '5' - '6' security: - Authentication: [] tags: - name: User description: Operations for creating, updating, retrieving, and managing user profiles. - name: Event description: Operations for tracking user events. - name: Device description: Operations for managing user devices. - name: Tracking description: Endpoints for tracking attribution and installs. - name: Utilities description: Utility endpoints for testing connections. - name: File Imports description: Operations for managing asynchronous file imports. - name: Bulk description: Operations for importing users and events in bulk. - name: Webhooks description: Incoming webhook specifications from MoEngage. paths: /customer/{app_id}: post: tags: - User summary: Track User description: This API helps add or update users and user properties in MoEngage. parameters: - name: app_id in: path required: true description: >- This is the Workspace ID of your MoEngage account that has to be passed along with the request. You can find your Workspace ID at Settings > Account > APIs > Workspace ID. schema: type: string example: VJ0GSMESHMQA3L7WV1EEK3UR - name: X-Forwarded-For in: header required: false description: > The 'X-Forwarded-For' header is used to specify the IP address of the client that made the request. This header may be added by proxy servers or load balancers. The header value must contain the IP address of the original client that initiated the request. Multiple IP addresses may be specified in the header value, separated by commas. schema: type: string example: 203.0.113.195 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateUserRequest' examples: sample_cURL: summary: Simple User Update value: type: customer customer_id: john@example.com attributes: name: JohnDoe first_name: John platforms: - platform: ANDROID active: 'true' example_payload: summary: Full User Update with Custom Attributes value: type: customer customer_id: john@example.com update_existing_only: true attributes: points: 20 expiry_date: '2020-05-31T03:47:35Z' super_user: true user_persona: browsers platforms: - platform: ANDROID active: 'true' responses: '200': description: >- This response is returned when the request is processed successfully. content: application/json: schema: $ref: '#/components/schemas/GenericSuccess' examples: success_response: summary: Success Response value: status: success message: Your request has been accepted and will be processed soon. '400': description: >- This response is returned when the required parameters are missing from the request, attributes are not found, and incorrect values are passed. content: application/json: schema: type: object properties: status: type: string description: >- This field contains the status of the request and specifies whether the request was a failure. example: fail error: type: object properties: attribute: type: string description: The attribute in the payload that caused the error. message: type: string description: >- A descriptive error message explaining why the request failed. type: type: string description: >- The type or category of the error ("MissingAttributeError"). request_id: type: string description: >- A unique identifier for the request, useful for debugging. examples: missing_customer_id: summary: Customer ID is missing in the payload value: status: fail error: attribute: customer_id message: customer_id is not found in the payload type: MissingAttributeError request_id: ZbPXtKFL empty_customer_id: summary: Customer ID is empty value: status: fail error: attribute: customer_id message: customer_id can not be empty Unicode String type: MissingAttributeError request_id: VgjtLxTu array_field_error: summary: Array field error value: status: fail error: attribute: addValueToArrayField message: Cannot add and remove 'first_name' at the same time type: ArrayFieldError request_id: WPDAbugh '401': description: >- This response is returned when the request does not have valid authentication credentials. content: application/json: schema: type: object properties: status: type: string example: fail error: type: object properties: message: type: string description: >- A descriptive error message explaining why the request failed. type: type: string description: >- The type or category of the error (e.g., Authentication required). request_id: type: string description: >- A unique identifier for the request, useful for debugging. examples: auth_error: summary: Authorization errors value: status: fail error: message: >- App Secret key mismatch. Please login to the dashboard to verify key type: Authentication required request_id: PVUDFisO missing_header: summary: Missing authentication header value: status: fail error: message: Authentication Header Required type: Authentication required request_id: PisPjGQQ '403': description: >- This response is returned when your MoEngage account is suspended or blocked. content: application/json: schema: type: object properties: status: type: string example: fail error: type: object properties: message: type: string description: >- A descriptive error message explaining why the request failed.(e.g., Your account is suspended. Please contact MoEngage team.) type: type: string description: >- The type or category of the error (e.g., BlockedClient, Account Suspended, Account Temporarily Suspended). request_id: type: string description: >- A unique identifier for the request, useful for debugging. examples: account_blocked: summary: Account is blocked value: status: fail error: message: Your account is blocked. Please contact MoEngage team. type: BlockedClient request_id: Block123 account_suspended: summary: Account is suspended value: status: fail error: message: Your account is suspended. Please contact MoEngage team. type: Account Suspended request_id: Susp123 temp_suspended: summary: Account is temporarily suspended value: status: fail error: message: >- Your account is temporarily suspended due to payment issues. type: Account Temporarily Suspended request_id: TempSusp123 '413': description: This response is returned when the payload size exceeds 128 KB. content: application/json: schema: type: object properties: status: type: string example: fail error: type: object properties: message: type: string description: >- A descriptive error message explaining why the request failed. type: type: string description: >- The type or category of the error (e.g., Payload too large). request_id: type: string description: >- A unique identifier for the request, useful for debugging. examples: payload_exceeded: summary: Payloads exceeding the size limit value: status: fail error: message: Payload size exceeds 128 KB type: PayloadTooLarge request_id: VFzDwhwt '415': description: This response is returned when the content type is not supported. content: application/json: schema: type: object properties: status: type: string example: fail error: type: object properties: message: type: string description: >- A descriptive error message explaining why the request failed. type: type: string description: >- The type or category of the error (e.g., Unsupported media type). request_id: type: string description: >- A unique identifier for the request, useful for debugging. examples: unsupported_media_type: summary: Unsupported media type value: status: fail error: message: Unsupported Media Type type: MediaTypeError request_id: SgBQfKJh '429': description: >- This response is returned when the number of requests has exceeded the rate limit. content: application/json: schema: type: object properties: status: type: string example: fail error: type: object properties: message: type: string description: >- A descriptive error message explaining why the request failed. type: type: string description: >- The type or category of the error (e.g., Rate Limits Exceeded). request_id: type: string description: >- A unique identifier for the request, useful for debugging. examples: rate_limit: summary: Rate limit breach value: status: fail error: message: Rate limit exceeded type: RateLimitError request_id: onqucLYL '500': description: >- This response is returned when the system runs into an unexpected error. content: application/json: schema: type: object properties: status: type: string example: fail error: type: object properties: message: type: string description: >- A descriptive error message explaining why the request failed. type: type: string description: >- The type or category of the error (e.g., Server Error). request_id: type: string description: >- A unique identifier for the request, useful for debugging. examples: unknown_error: summary: Unknown errors value: status: fail error: message: Internal Server Error type: ServerError request_id: KovrwJiF components: schemas: CreateUserRequest: title: User type: object required: - type - customer_id properties: type: type: string description: >- This is used to identify the type of request. This field is case-sensitive. Follow the case as in the example when passing the value in the request. enum: - customer customer_id: type: string description: > The unique identifier is used to identify/create a user in MoEngage. Not mandatory in [Identity Resolution](https://help.moengage.com/hc/en-us/articles/24050999467284-Unified-Identity-Identity-Resolution) enabled workspaces If the User Identity Resolution feature is enabled in your workspace, the attribute parameters in the payload must contain at least one of the identifiers you have activated in your workspace based on which users in MoEngage will be created, updated, or merged. In the following example, moe_mobile is one of the identifiers in the workspace and is passed in attributes: ```json { "type": "customer", "attributes": {"moe_mobile": "{{Mobile_Number}}", "first_name": "John" } } ```' update_existing_only: type: boolean default: false description: > This field should be passed in the request when only existing users in MoEngage should be updated. **If this value is passed as true:** 1. Only those users for whom the customer_id from the request payload matches the customer identifier in MoEngage will be updated. 2. In case of new users (customer_id in the payload does not match any of the existing customer ids in your MoEngage account), they will not be created. **If this value is passed as false:** 1. The user attributes will be updated with the values present in the payload for existing customers. 2. In case of new users (customer_id in the payload does not match any of the existing customer ids in your MoEngage account), a new customer will be created in the system with the details specified in the payload. attributes: $ref: '#/components/schemas/UserAttributes' platforms: type: array description: >- List of dictionaries with the associated platforms out of ANDROID, iOS, and web and their status. items: $ref: '#/components/schemas/PlatformObject' GenericSuccess: type: object properties: status: type: string description: >- This field contains the status of the request and specifies whether the request was successful. example: success message: type: string example: Your request has been accepted and will be processed soon. UserAttributes: type: object description: > A dictionary containing user attributes to add / update in the user profile. For example, to track custom attributes of different data types like string, numeric, boolean, and date, pass the following payload where points are a number, expiry_date is a date type attribute, and super_user is a boolean attribute. > **Note:** > * "id", "_id", and "" keywords are blocked and not to be used as user attribute names. > * You can not use "moe_" as a prefix while naming user attributes. It is a system prefix and using it might result in periodic blacklisting without prior communication. > For other attributes that are not listed below, use the key-value pairs that you intend to use. properties: u_n: type: string description: Full name of the user. u_fn: type: string description: First name of the user. u_ln: type: string description: Last name of the user. u_gd: type: string description: Gender of the user. u_em: type: string format: email description: Email Address of the user (Standard). u_mb: type: string description: Mobile Number of the user (Standard). Example `918888444411`. uid: type: string description: >- A unique ID that the app has set for a user. This is a standard attribute where MoEngage provides the name, and the value is provided by the client. u_bd: type: string format: date-time description: >- Birthdate of the user in ISO 8601 format (e.g., 2019-05-21T03:47:35Z). moe_wa_subscription: type: boolean description: WhatsApp subscription status of a user. moe_em_unsub_categories: type: string description: >- Email Unsubscribed Categories. The list of email categories user has unsubscribed. push_preference: type: boolean description: >- Push Opt In Status (iOS).The push permission status of a user on an iOS device. moe_sub_w: type: boolean description: >- Web Push Subscription Status. The web push subscription status of a user. Use this to find your aggregate subscribers and users who unsubscribed after subscribing once. moe_spam: type: boolean description: >- Spam. Email Spam Attribute. The emails are not sent to the user when the set value is true. moe_unsubscribe: type: boolean description: >- Unsubscribe. Email Unsubscribe Attribute. Emails are not sent to the user when the set value is true. moe_hard_bounce: type: boolean description: >- Hard Bounce. Email Hard Bounce Attribute. The emails are not sent to the user when the set value is true. moe_sms_subscription: type: string description: >- SMS Subscription Status. An attribute which stores the SMS subscription status of the user. This will be used to see if a user is reachable based on certain values of the attribute. moe_email_optin_status: type: string enum: - DOUBLE_OPTED_IN - OPTED_OUT - OPT_IN_PENDING description: > Email Opt-in Status. An attribute that stores the opt-in status of the user for the email channel. Supported values are: * `DOUBLE_OPTED_IN` * `OPTED_OUT` * `OPT_IN_PENDING` additionalProperties: true example: name: John points: 20 expiry_date: '2020-05-31T03:47:35Z' super_user: true user_persona: browsers PlatformObject: type: object properties: platform: type: string enum: - ANDROID - iOS - web active: type: string enum: - 'true' - 'false' securitySchemes: Authentication: type: http scheme: basic description: > This authentication parameter, used for access control, must be passed along with the request. The API request will be authenticated through Basic Authentication. Basic Authentication sends a Base64-encoded string containing your username and password with every API request. It encodes a 'username:password' string in Base64 and appends the encoded string with 'Basic '. This string is included in the authorization header as shown below: `{"Authorization: Basic Base64_ENCODED_WORKSPACEID_APIKEY=="}` The username and password details can be obtained from the MoEngage Dashboard. If you're using the API for the first time, follow these steps: 1. Navigate to Settings -> Account -> APIs. 2. Copy the following details: * **Username:** Under Workspace ID (earlier app id), click the copy icon to copy the username. * **Password:** In the **API keys** section, click the copy icon in the **Data** tile to copy the API key. Use these details to authenticate the API requests. ````