Affiliates API

This section details the API endpoints for managing affiliate records associated with your company.

Endpoint: /affiliates Base URL: https://app.integrishield.com/api

List Affiliates

Method: GET
Full Endpoint: https://app.integrishield.com/api/affiliates
Description: Retrieves a list of all affiliates associated with your company.
Authentication: Required (Bearer Token).

Success Response (200 OK):

Returns a JSON object containing the list of affiliates in the data array.

{
  "code": "1026",
  "status": "ok",
  "detail": {
    "msg": "Affiliates found"
  },
  "data": [
    {
      "id": 1,
      "client_id": 10,
      "client_distributor_id": "YOUR-AFF-ID-001",
      "distributor_name": "Affiliate One Name",
      "email_one": "affiliate.one@example.com",
      "distributor_status": "active",
      "country": 1,
      "pay_rank": "Gold",
      "recognition_rank": "Top Seller",
      ...
    }
  ]
}

Note: Response field names reflect internal storage names (e.g., distributor_name, client_distributor_id, distributor_status). These correspond directly to the API input fields (affiliate_name, client_affiliate_id, status) listed in the Affiliate Data Fields reference below.

Get Single Affiliate

Method: GET
Full Endpoint: https://app.integrishield.com/api/affiliates/{id}
Description: Retrieves details for a specific affiliate by their unique Integrishield ID.
Authentication: Required (Bearer Token).

Path Parameters:

Parameter	Type	Required	Description
`id`	integer	Yes	The unique ID assigned by Integrishield (found via List or Create responses).

Example Request:

GET /api/affiliates/126

Success Response (200 OK):

Returns a JSON object containing the affiliate data.

{
  "code": "1026",
  "status": "ok",
  "detail": {
    "msg": "Affiliate found."
  },
  "data": {
    "id": 1,
    "client_id": 10,
    "client_distributor_id": "YOUR-AFF-ID-001",
    "distributor_name": "Affiliate One Name",
    "email_one": "affiliate.one@example.com",
    "distributor_status": "active",
    "country": 1,
    "pay_rank": "Gold",
    "recognition_rank": "Top Seller",
    ...
  }
}

Error Response (404 Not Found):

Returned if no affiliate exists with the specified ID, or the affiliate does not belong to your company.

{
  "code": "1025",
  "status": "error",
  "detail": {
    "msg": "Affiliate not found against the provided Affiliate-ID."
  }
}

Create Affiliate(s)

Method: POST
Full Endpoint: https://app.integrishield.com/api/affiliates
Description: Creates one or more new affiliates for your company. Supports single or batch creation. Duplicates based on affiliate_name within your company are skipped.
Authentication: Required (Bearer Token).

Request Body (Single Affiliate):

A JSON object with the affiliate's details. client_affiliate_id and affiliate_name are required. See the Affiliate Object Reference for all available fields.

{
  "client_affiliate_id": "YOUR-AFF-ID-003",
  "affiliate_name": "New Affiliate Three",
  "email_one": "new.three@example.com",
  "country": "US",
  "status": "active"
}

Request Body (Multiple Affiliates):

A JSON object with a single key affiliates containing an array of affiliate objects. client_affiliate_id and affiliate_name are required within each object.

{
  "affiliates": [
    {
      "client_affiliate_id": "YOUR-MULTI-1",
      "affiliate_name": "Multi Affiliate One",
      "country": "CA",
      "status": "active"
    },
    {
      "client_affiliate_id": "YOUR-MULTI-2",
      "affiliate_name": "Multi Affiliate Two",
      "status": "inactive"
    }
  ]
}

Success Response (Single - 201 Created):

Confirms creation and returns the new Integrishield ID (affiliate_id).

{
  "code": "1020",
  "status": "ok",
  "detail": {
    "affiliate_id": 126,
    "client_affiliate_id": "YOUR-AFF-ID-003",
    "msg": "Affiliate added successfully."
  }
}

Success Response (Multiple - 201 Created or 207 Multi-Status):

Returns a JSON array with results for each submitted affiliate. HTTP status is 201 if all succeed, 207 if there are mixed results (successes and handled errors like duplicates or invalid country codes).

[
  {
    "code": "1020",
    "status": "ok",
    "detail": {
      "affiliate_id": 127,
      "client_affiliate_id": "YOUR-MULTI-1",
      "msg": "Affiliate added successfully."
    }
  },
  {
    "code": "1023",
    "status": "error",
    "detail": {
      "client_affiliate_id": "YOUR-MULTI-2",
      "msg": "`Affiliate Name` already exists."
    }
  },
  {
    "code": "1024",
    "status": "error",
    "detail": {
      "client_affiliate_id": "YOUR-MULTI-3",
      "msg": "Invalid `ISO-2 country code`."
    }
  }
]

Error Responses:

409 Conflict: (Single Create Only) If an affiliate with the same affiliate_name already exists.
422 Unprocessable Entity: If validation fails (missing required fields, invalid formats, etc.). Check the errors object in the response body for details on which fields failed and why.

Update Affiliate(s)

Method: PUT
Full Endpoint: https://app.integrishield.com/api/affiliates/{id}
Description: Updates one or more existing affiliates.
- Single Update: Use the affiliate's unique Integrishield ID in the URL ({id}). The request body MUST also contain an id field with the same value.
- Multiple Update: Use any valid affiliate ID in the URL (it's ignored). The request body MUST contain an affiliates array, and each object within that array MUST have the id (Integrishield ID) of the affiliate to update.
Authentication: Required (Bearer Token).

Path Parameters:

Parameter	Type	Required	Description
`id`	integer	Yes	The unique Integrishield ID (required for single update; ignored for bulk updates).

Request Body (Single Affiliate Update):

JSON object with fields to update. Must include id matching the URL. See the Affiliate Object Reference for all available fields.

{
  "id": 126,
  "affiliate_name": "Updated Affiliate Name",
  "status": "probation",
  "notes": "Account under review.",
  "pay_rank": "Bronze"
}

Request Body (Multiple Affiliates Update):

JSON object with an affiliates array. Each object must include id (Integrishield ID) and the fields to update for that specific affiliate.

{
  "affiliates": [
    {
      "id": 127,
      "status": "terminated",
      "notes": "Account terminated due to violation."
    },
    {
      "id": 128,
      "affiliate_name": "Affiliate Renamed Ltd.",
      "phone_one": "555-111-2222",
      "pay_rank": "Platinum"
    }
  ]
}

Success Response (Single - 200 OK):

{
  "code": "1020",
  "status": "ok",
  "detail": {
    "affiliate_id": 126,
    "msg": "Affiliate updated successfully."
  }
}

Success Response (Multiple - 200 OK or 207 Multi-Status):

Returns a JSON array with results for each submitted update attempt. HTTP status is 200 if all succeed, 207 if there are mixed results.

[
  {
    "code": "1020",
    "status": "ok",
    "detail": {
      "affiliate_id": 127,
      "msg": "Affiliate updated successfully."
    }
  },
  {
    "code": "1025",
    "status": "error",
    "detail": {
      "affiliate_id": 999,
      "msg": "Affiliate not found against the provided Affiliate-ID."
    }
  },
  {
    "code": "1021",
    "status": "error",
    "detail": {
      "affiliate_id": 128,
      "msg": "Failed to update affiliate. Server error."
    }
  }
]

Error Responses:

404 Not Found: (Single Update Only) If the affiliate ID in the URL doesn't exist or belong to your company.
422 Unprocessable Entity: If validation fails (e.g., id missing in payload, invalid field formats). Check the errors object in the response body for details.

Affiliate Object Reference

The following table lists the fields available when creating or updating affiliates via the API. Use these field names in your JSON request bodies.

Field	Type	Required (Create)	Description	Max Length	Validation Notes
`client_affiliate_id`	string	Yes	Your unique identifier for the affiliate.	64
`affiliate_name`	string	Yes	Name of the affiliate.	128	Must be unique within your company.
`email_one`	string	No	Primary email address.	50	Must be a valid email format.
`email_two`	string	No	Secondary email address.	50	Must be a valid email format.
`phone_one`	string	No	Primary phone number.	30
`phone_two`	string	No	Secondary phone number.	128
`facebook`	string	No	Facebook profile/page URL.	128
`instagram`	string	No	Instagram profile URL/handle.	255
`youtube`	string	No	YouTube channel/profile URL.	128
`twitter`	string	No	Twitter profile URL/handle.	64
`tiktok`	string	No	TikTok profile URL/handle.	64
`pintrest`	string	No	Pinterest profile URL/handle.	64
`country`	string	No	ISO 2-letter country code (e.g., "US", "CA", "GB").	2	Must be exactly 2 characters.
`first_name`	string	No	Affiliate's first name.	128
`last_name`	string	No	Affiliate's last name.	64
`notes`	string	No	Internal notes about the affiliate.	2048
`address`	string	No	Street address.	512
`city`	string	No	City name.	64
`state`	string	No	State or province name/code.	64
`zip`	string	No	Postal code / ZIP code.	16
`ranking`	string	No	Affiliate's ranking.	64
`replicated_website`	string	No	URL of the affiliate's replicated website.	256	Must be a valid URL format.
`sponsor`	string	No	Name of the affiliate's sponsor.	64
`upline`	string	No	Information about the affiliate's upline.	255
`status`	string	No	Current status of the affiliate.	-	Must be one of: `active`, `inactive`, `probation`, `suspended`, `terminated`, `forgotten`.
`start_date`	string	No	Affiliate start date (format: `YYYY-MM-DD` or `MM/DD/YYYY`).	10
`language_used`	string	No	Primary language used by the affiliate.	64
`territory`	string	No	Assigned territory.	64
`entrepreneur_id`	string	No	Entrepreneur ID, if applicable.	255
`entrepreneur_spouse_id`	string	No	Spouse's Entrepreneur ID, if applicable.	255
`international_distributor`	string	No	Flag or identifier for international status.	255
`is_territory_director`	string	No	Flag or identifier for territory director status.	255
`jv_status`	string	No	Joint Venture status, if applicable.	255
`league`	string	No	League or group affiliation.	255
`territory_master`	string	No	Territory Master identifier, if applicable.	255
`merchant_type`	string	No	Type of merchant, if applicable.	255
`company_name`	string	No	Affiliate's company name, if applicable.	255
`sponsor_id`	string	No	ID of the affiliate's sponsor.	64
`sponsor_email`	string	No	Email address of the affiliate's sponsor.	255	Must be a valid email format.
`pay_rank`	string	No	Affiliate's pay rank.	64
`recognition_rank`	string	No	Affiliate's recognition rank.	64

Common Error Responses

401 Unauthorized: If the Bearer token is missing, invalid, or expired.
429 Too Many Requests: If you exceed the API rate limit. Wait before retrying.
500 Internal Server Error: If an unexpected error occurs on the server during processing.

{
  "code": "500",
  "status": "error",
  "detail": {
    "msg": "Server error! Contact server admin."
  }
}

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search