Introduction

Purpose: This article explains how to use the Open Invite API to create or fetch invitee records for your referral or ambassador program.
Context: The Open Invite API allows you to manage users who have been invited to your program and users who have already registered as ambassadors. It supports both new invite creation and the retrieval of existing ambassador records.

In this guide, you’ll learn how to:

Use the Open Invite endpoint
Understand successful and error responses
Distinguish between InvitedAmbassador and Ambassador data

Endpoint Overview

API: https://socialladder.rkiapps.com/SocialLadderAPI/api/v1/ambassador/openinvite?areaGuid=[AREA_GUID]&externalUserId=[CUSTOMER_ID]

Method: POST

Purpose: Create or retrieve an existing invitee record (either an Invited Ambassador or a Registered Ambassador).

Parameters:

areaGuid
- This will be provided by the SocialLadder team and is required for the endpoint to work. If you have not received your areaGuid, please reach out to you Implementation Specialist.
externalUserId
- This is the customer Id of the user that is logged into their account on your website.

The API accepts basic invitee information (such as email, tags, and custom data) and returns a structured response depending on whether the user already exists, was newly invited, or if an error occurred.

Request Model:

{
  "first_name": "string",
  "last_name": "string",
  "email_address": "string",
  "phone": {
    "phone_number": "string",
    "country_code": "string"
  },
  "custom_data": [
    {
      "field_name": "string",
      "field_value": "string"
    }
  ],
  "tags": [
    "string"
  ],
  "promo_code": "string"
}

Fields terminology and description

custom_data
- field_name: These are the custom fields created on the portal. The endpoint will only support fields which exist on the portal. Unsupported fields will be ignored.
  - In case, the field type is a predefined list, the undefined values in field_value will be ignored.

Validations:

areaGuid: Should be valid.
email_address: Should be unique.
externalUserId: Should be unique.

✅ Success Response Structure

Every successful API response includes the following top-level properties:

Property	Type	Description
success	boolean	Indicates whether the request was processed successfully.
code	integer	Numeric response code (see Response Codes).
message	string	Human-readable description of the result.
type	string	Defines the object type returned (e.g., Ambassador, InvitedAmbassador, Error).
data	object	Contains detailed information about the invitee or ambassador.

🧩 Response Codes

Code	Meaning	Type	Description
100	Success	Ambassador or InvitedAmbassador	User found or created successfully.
400	Bad Request	Error	Invalid parameters or email.
401	Unauthorized	Error	Invalid Area GUID.
409	Conflict	ValidationError	Duplicate validation error.
500	Server Error	Error / Exception	Internal server issue.

🧑‍💻 Response Types

Type	Description
Ambassador	The user is already registered in your program.
InvitedAmbassador	The user has been invited but not yet registered.
Error / ValidationError / Exception	The request failed (invalid input, duplicate data, or system error).

📨 Example: Invited Ambassador Created

When you invite a new user, the API returns an object of type InvitedAmbassador:

{
  "success": true,
  "code": 100,
  "message": "Invited Ambassador created successfully",
  "type": "InvitedAmbassador",
  "data": {
    "id": 1234,
    "externalCRMId": "EXT_CRM_1234",
    "inviteSent": "2025-11-06T09:19:46.91",
    "status": "INVITED",
    "referralLinks": [
      {
        "campaignName": "Campaign Name",
        "trackngKey": "123e4567-e89b-12d3-a456-426655440000",
        "referralLink": "https://click-myl.ink/a1b2c3d4"
      }
    ],
    "email": "example@example.com",
    "promo_code": "CODE123",
    "tags": ["Newsletter", "VIP"],
    "custom_data": [
      { "field_name": "First_Name", "field_value": "John" },
      { "field_name": "Last_Name", "field_value": "Doe" },
      { "field_name": "Phone_Number", "field_value": "1234567890" },
      { "field_name": "EXTERNAL_CRM_ID", "field_value": "EXT_CRM_1234" }
    ]
  }
}

Key Fields

inviteSent → Timestamp when the invitation was created.
status → "INVITED" until the user registers.
referralLinks → Array of referral tracking links tied to active campaigns.
custom_data → Your CRM or app-specific metadata.

👤 Example: Ambassador Already Exists

If the invitee is already a registered user (an Ambassador), you’ll receive this response:

JSON
{
  "success": true,
  "code": 100,
  "message": "Ambassador already exists",
  "type": "Ambassador",
  "data": {
    "id": 1234,
    "profilePic": "https://res.cloudinary.com/socialladder/image/upload/r_max,w_150,h_150/profile.png",
    "dateAdded": "2025-11-04T11:05:26.12",
    "profilePicLarge": "http://res.cloudinary.com/socialladder/image/upload/w_640,h_400/profile.jpg",
    "userName": "John Doe",
    "salesCurrency": "USD",
    "email": "example@example.com",
    "status": "Active",
    "promo_code": "CODE123",
    "tags": ["Newsletter", "VIP"],
    "custom_data": [

      { "field_name": "Phone_Number", "field_value": "+11234567890" },
      { "field_name": "EXTERNAL_CRM_ID", "field_value": "EXT_CRM_1234" },
      { "field_name": "Last_Name", "field_value": "Doe" },
      { "field_name": "First_Name", "field_value": "John" }
    ],
    "referralLinks": [
      {
        "campaignName": "Campaign Name",
        "trackngKey": "123e4567-e89b-12d3-a456-426655440000",
        "referralLink": "https://click-myl.ink/a1b2c3d4"
      }
    ]
  }
}

Key Differences

Field	InvitedAmbassador	Ambassador
status	INVITED	ACTIVE
inviteSent	✅ Present	❌ Not applicable
profilePic / userName	❌ Not applicable	✅ Present
custom_data	May include partial fields	Full user profile fields
referralLinks	✅	✅

How To Use The Open Invite API