> ## Documentation Index
> Fetch the complete documentation index at: https://docs.invoca.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Affiliates

The operations on Affiliate are similar to Network, in that the interface is fully idempotent, and the create and update commands both expect the full set of affiliate sites and users each time. Similar to advertisers, you are not allowed to delete if one or more campaigns exist for this affiliate.

| Property | Type | Value |
| - | - | - |
| id | integer (read-only) | The internal Invoca id for this Affiliate. |
| id\_from\_network | string | The network object\_id for this Affiliate. Unique within network. Not required when auto-generation is enabled at network level. |
| name | string | The name of the Affiliate. Unique within the network. |
| status | string (one of): Applied, Approved (default), Declined, Suspended, Archived | Approval status for this affiliate. |
| object\_url | string (read-only) | URL for reaching the affiliate in the UI. |
| sites | json array of hashes | 1 or more pairs of id\_from\_network \[and name]. |
| id\_from\_network | string | The site id (PID). |
| name | string | The site name that matches site id\_from\_network. |
| users | JSON array of hashes | 0 or more users for the organization. Each must have first 5 fields below. |
| id\_from\_network | string | The network id for this User. |
| email\_settings | JSON array of hashes | Each hash has two required fields: email\_address: string in RFC 2822 addr-spec format. The user’s email address. Unique for this user. use\_for\_notifications: boolean used to indicate if notifications should be sent to the email address. A user must have at least one email address where use\_for\_notifications is true. |
| first\_name | string (Required) | The user’s first name. |
| last\_name | string (Required) | The user’s last name. |
| contact\_phone\_number | string in ITU E.164 format or 10-digit US form (no punctuation) | The user’s phone number. |
| oauth\_refresh\_token | string | Not used. Reserved. |
| role | One of: Super (default), Manager, Member, Observer | This user’s role in this organization. (A user may have different roles in different organizations) |
| notify\_on\_budgets | boolean, optional, defaults to false | |
| notify\_on\_campaign\_applications | boolean, optional, defaults to false | |
| notify\_on\_campaign\_expirations | boolean, optional, defaults to false | |
| notify\_on\_creative\_duplication\_requests | boolean, optional, defaults to false | |
| notify\_on\_network\_announcements | boolean, optional, defaults to false | |
| notify\_on\_performance\_notifications | Deprecated, always returns false | |
| notify\_on\_monthly\_campaign\_performance\_reports | Deprecated, always returns false | |
| notify\_on\_weekly\_campaign\_performance\_reports | Deprecated, always returns false | |
| notify\_on\_call\_activities | boolean, optional, defaults to false | |
| can\_login\_via\_platform | boolean (read-only) | Indicates if user can directly login with username and password. If false, the user is managed via SSO. |

## Custom Data

Affiliates may have Custom Data Fields applied to them, which will be applied to calls originating through the affiliate. To apply Custom Data Values to an affiliate, the top level parameter `custom_data` should be assigned a hash with each pair’s key corresponding to a partner name. The value of the pair should be the value to be applied.

For the following example, we would apply the value “Offline newspaper” to the Custom Data Field “channel”.

```json theme={null}
{
  "custom_data": {
    "channel": "Offline newspaper"
  }
}
```

Endpoint:

`https://invoca.net/api/2022-08-01/<network_id>/affiliates/<affiliate_id_from_network>.json`

> [accordion] Get all Affiliates
>
> #### Examples
>
> Read all Affiliates for this network
>
> Endpoint:
>
> `https://invoca.net/api/2022-08-01/<network_id>/affiliates.json`
>
> Response Body:
>
> ```json theme={null}
> [
>   {
>     "id": 19,
>     "id_from_network": "222",
>     "object_url": "https://invoca.net/ps/19/dashboards/ui",
>     "sites": [
>       {
>         "id_from_network": "33567",
>         "name": "http://www.surfoz.au"
>       },
>       {
>         "id_from_network": "44920",
>         "name": "http://www.blogspot.com/surfoz"
>       }
>     ],
>     "name": "Surf Oz Magazine",
>     "users": [
>       {
>         "email_settings": [
>           { "email_address": "userx@invoca.com",  "use_for_notifications": true }
>         ],
>         "id_from_network": "1231",
>         "first_name": "User",
>         "phone_number": "805‐708‐9876",
>         "last_name": "Affiliate",
>         "role": "Super",
>         "oauth_refresh_token": "556588585858585858585858858",
>         "notify_on_budgets": true,
>         "notify_on_campaign_applications": false,
>         "notify_on_campaign_expirations": false,
>         "notify_on_creative_duplication_requests": true,
>         "notify_on_network_announcements": true,
>         "notify_on_performance_notifications": false,
>         "notify_on_monthly_campaign_performance_reports": false,
>         "notify_on_weekly_campaign_performance_reports": false,
>         "notify_on_call_activities": true,
>         "can_login_via_platform": true
>       }
>     ],
>     "status": "Approved",
>     "custom_data": {
>       "channel": "Online lead"
>     }
>   }
> ]
> ```

> [accordion] Get an Affiliate
>
> #### Examples
>
> Read a specific affiliate
>
> Endpoint:
>
> `https://invoca.net/api/2022-08-01/<network_id>/affiliates/222.json`
>
> Response Body:
>
> ```json theme={null}
> {
>   "id": 19,
>   "id_from_network": "222",
>   "object_url": "https://invoca.net/ps/19/dashboards/ui",
>   "sites": [
>     {
>       "id_from_network": "33567",
>       "name": "http://www.surfoz.au"
>     },
>     {
>       "id_from_network": "44920",
>       "name": "http://www.blogspot.com/surfoz"
>     }
>   ],
>   "name": "Surf Oz Magazine",
>   "users": [
>     {
>       "email_settings": [
>         { "email_address": "userx@invoca.com", "use_for_notifications": true }
>       ],
>       "id_from_network": "1231",
>       "first_name": "User",
>       "phone_number": "805‐708‐9876",
>       "last_name": "Affiliate",
>       "role": "Super",
>       "oauth_refresh_token": "556588585858585858585858858",
>       "notify_on_budgets": true,
>       "notify_on_campaign_applications": false,
>       "notify_on_campaign_expirations": false,
>       "notify_on_creative_duplication_requests": true,
>       "notify_on_network_announcements": true,
>       "notify_on_performance_notifications": false,
>       "notify_on_monthly_campaign_performance_reports": false,
>       "notify_on_weekly_campaign_performance_reports": false,
>       "notify_on_call_activities": true,
>       "can_login_via_platform": true
>     }
>   ],
>   "status": "Approved",
>   "custom_data": {
>     "channel": "Online lead"
>   }
> }
> ```

> [accordion] Delete an Affiliate
>
> #### Examples
>
> Delete a single affiliate
>
> Endpoint:
>
> `https://invoca.net/api/2022-08-01/<network_id>/affiliates/222.json`
>
> Response Body:
>
> ```json theme={null}
> {
> }
> ```

> [accordion] Create an Affiliate
>
> #### Examples
>
> Create an affiliate with users
>
> Endpoint:
>
> `https://invoca.net/api/2022-08-01/<network_id>/affiliates.json`
>
> Format: application/json
>
> Request Body:
>
> ```json theme={null}
> {
>   "name": "Surf Oz Magazine",
>   "status": "Approved",
>   "id_from_network": "222",
>   "users": [
>     {
>       "phone_number": "805‐708‐9876",
>       "id_from_network": 123,
>       "role": "Super",
>       "last_name": "Affiliate",
>       "first_name": "User",
>       "email_settings": [
>         { "email_address": "userx@invoca.com",  "use_for_notifications": true }
>       ],
>       "notify_on_budgets": true,
>       "notify_on_campaign_applications": false,
>       "notify_on_campaign_expirations": false,
>       "notify_on_creative_duplication_requests": true,
>       "notify_on_network_announcements": true,
>       "notify_on_call_activities": true
>     }
>   ],
>   "sites": [
>     {
>       "id_from_network": 33567,
>       "name": "http://www.surfoz.au"
>     },
>     {
>       "id_from_network": 44920,
>       "name": "http://www.blogspot.com/surfoz"
>     }
>   ],
>   "custom_data": {
>     "channel": "Offline lead"
>   }
> }
> ```
>
> Response Body:
>
> Same as a GET response, includes all the affiliate properties.

> [accordion] Update an Affiliate
>
> #### Examples
>
> Update a single affiliate
>
> Endpoint:
>
> `https://invoca.net/api/2022-08-01/<network_id>/affiliates/222.json`
>
> Request Body:
>
> ```json theme={null}
> {
>   "name": "Updated Surf Oz Magazine"
> }
> ```
>
> Response Body:
>
> Same as a GET response, includes all the affiliate properties.


## Related topics

- [Affiliate Campaigns](https://docs.invoca.com/en/latest/api_documentation/network_integration/affiliate_campaigns/index.md)
- [Publisher / Affiliate](https://docs.invoca.com/en/latest/api_documentation/transactions_api/affiliate_user.md)
- [Auto-Approve Affiliate to Campaigns](https://docs.invoca.com/en/latest/api_documentation/network_integration/advertiser_affiliate_relationships/index.md)
- [How to Approve a Publisher to Your Affiliate Campaign](https://docs.invoca.com/s/article/approve-publisher-affiliate-campaign.md)
- [How Do I Pay Out Affiliates Based on the Region of the Caller?](https://docs.invoca.com/s/article/payout-affiliates-by-region.md)