> ## 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.

# Advertisers

export const MethodTag = ({method = "GET", path, label, colors = {}}) => {
  const presets = {
    get: {
      label: "GET",
      light: {
        bg: "#DCFCE7",
        text: "#15803D"
      },
      dark: {
        bg: "rgba(34,197,94,0.16)",
        text: "#4ADE80"
      }
    },
    post: {
      label: "POST",
      light: {
        bg: "#DBEAFE",
        text: "#1D4ED8"
      },
      dark: {
        bg: "rgba(59,130,246,0.16)",
        text: "#60A5FA"
      }
    },
    put: {
      label: "PUT",
      light: {
        bg: "#FEF3C7",
        text: "#B45309"
      },
      dark: {
        bg: "rgba(245,158,11,0.16)",
        text: "#FBBF24"
      }
    },
    patch: {
      label: "PATCH",
      light: {
        bg: "#F3E8FF",
        text: "#7E22CE"
      },
      dark: {
        bg: "rgba(168,85,247,0.16)",
        text: "#C084FC"
      }
    },
    delete: {
      label: "DEL",
      light: {
        bg: "#FEE2E2",
        text: "#B91C1C"
      },
      dark: {
        bg: "rgba(239,68,68,0.16)",
        text: "#F87171"
      }
    }
  };
  const fallback = {
    label: String(method).toUpperCase(),
    light: {
      bg: "#F3F4F6",
      text: "#374151"
    },
    dark: {
      bg: "rgba(156,163,175,0.16)",
      text: "#D1D5DB"
    }
  };
  const preset = presets[String(method).toLowerCase()] || fallback;
  const light = {
    ...preset.light,
    ...colors.light || ({})
  };
  const dark = {
    ...preset.dark,
    ...colors.dark || ({})
  };
  const css = `
    .invoca-method-tag {
      display: inline-block;
      padding: 1px 8px;
      margin-right: 8px;
      border-radius: 8px;
      font-size: 10px;
      line-height: 18px;
      font-weight: 700;
      letter-spacing: 0.4px;
      text-transform: uppercase;
      vertical-align: middle;
      background: var(--imt-bg);
      color: var(--imt-fg);
    }
    .invoca-method-path {
      font-size: 13px;
    }
    [data-component-part="accordion-icon"]:has(.invoca-method-tag) {
      width: auto;
      height: auto;
      flex-shrink: 0;
    }
    [data-component-part="accordion-icon"] .invoca-method-tag {
      margin-right: 0;
    }
    [data-component-part="accordion-button"]:has(.invoca-method-tag) {
      flex-wrap: wrap;
      row-gap: 6px;
    }
    [data-component-part="accordion-button"]:has(.invoca-method-tag) [data-component-part="accordion-icon"] {
      flex: 1 1 0;
      min-width: 0;
      overflow-wrap: anywhere;
    }
    [data-component-part="accordion-button"]:has(.invoca-method-tag) [data-component-part="accordion-title-container"] {
      flex: 0 0 calc(100% - 8px);
      padding-left: 20px;
    }
    [data-component-part="accordion-button"]:has(.invoca-method-tag) [data-component-part="accordion-title"] {
      font-size: 12px;
    }
    .dark .invoca-method-tag,
    [data-theme="dark"] .invoca-method-tag {
      background: var(--imt-bg-dark);
      color: var(--imt-fg-dark);
    }
  `;
  const vars = {
    "--imt-bg": light.bg,
    "--imt-fg": light.text,
    "--imt-bg-dark": dark.bg,
    "--imt-fg-dark": dark.text
  };
  return <span>
      <style>{css}</style>
      <span className="invoca-method-tag" style={vars}>
        {label || preset.label}
      </span>
      {path ? <code className="invoca-method-path">{path}</code> : null}
    </span>;
};

The operations on Advertiser are similar to Network, in that the interface is fully idempotent, and the create and update commands both expect the full set of advertiser sites and users each time. You are not allowed to delete an advertiser if it has one or more campaigns.

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

## Custom Data

Advertisers may have Custom Data Fields applied to them, which will be applied to calls originating through the advertiser. To apply Custom Data Values to an advertiser, 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/2019-05-01/<network_id>/advertisers/<advertiser_id_from_network>.json`

<AccordionGroup>
  <Accordion title="Get all Advertisers" icon={<MethodTag method="get" path="/advertisers"/>}>
    #### Examples

    Read all advertisers for this network

    Endpoint:

    `https://invoca.net/api/2019-05-01/<network_id>/advertisers.json`

    Format: application/json

    Response Code: 200

    Response Body:

    ```json theme={null}
    [
      {
        "id": 43838,
        "id_from_network": "cFUyYnFHy",
        "web_integration_phone_number": "8004377950",
        "approval_status": "Approved",
        "object_url": "https://invoca.net/as/43838/dashboards/ui",
        "sites": [
          {
            "id_from_network": "315",
            "name": "315.blog.com"
          }
        ],
        "name": "NFL Tickets Exchange",
        "users": [
          {
            "id_from_network": "549494858585cFUyYnFHyiYA42TrpM",
            "email_settings": [
              { "email_address": "chris@nfltix.com", "use_for_notifications": true }
            ],
            "first_name": "Chris",
            "phone_number": "888‐603‐3760",
            "last_name": "Dean",
            "role": "Manager",
            "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": true,
            "notify_on_weekly_campaign_performance_reports": false,
            "notify_on_call_activities": true,
            "can_login_via_platform": true
          }
        ],
        "default_creative_id_from_network": "222",
        "oauth_refresh_token": "7464644784457575757494930303",
        "custom_data": {
          "channel": "Online lead"
        }
      }
    ]
    ```
  </Accordion>

  <Accordion title="Get an Advertiser" icon={<MethodTag method="get" path="/advertisers/<advertiser_id>"/>}>
    #### Examples

    Read a single advertiser

    Endpoint:

    `https://invoca.net/api/2019-05-01/<network_id>/advertisers/cFUyYnFHy.json`

    Format: application/json

    Response Code: 200

    Response Body:

    ```json theme={null}
    {
      "id": 43838,
      "id_from_network": "cFUyYnFHy",
      "web_integration_phone_number": "8004377950",
      "approval_status": "Approved",
      "object_url": "https://invoca.net/as/43838/dashboards/ui",
      "sites": [
        {
          "id_from_network": "315",
          "name": "315.blog.com"
        },
        {
          "id_from_network": "996",
          "name": "996.blog.com"
        }
      ],
      "name": "NFL Tickets Exchange",
      "users": [
        {
          "id_from_network": "549494858585cFUyYnFHyiYA42TrpM",
          "email_settings": [
            { "email_address": "chris@nfltix.com", "use_for_notifications": true }
          ],
          "first_name": "Chris",
          "phone_number": "888‐603‐3760",
          "last_name": "Dean",
          "role": "Manager",
          "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": true,
          "notify_on_weekly_campaign_performance_reports": false,
          "notify_on_call_activities": true,
          "can_login_via_platform": false
        },
        {
          "id_from_network": "694940505055cFUyYnFHyiYA42TrpM",
          "email_settings": [
            { "email_address": "jim@nfltix.com", "use_for_notifications": true }
          ],
          "first_name": "Jim",
          "phone_number": "888‐603‐3760",
          "last_name": "Williams",
          "role": "Observer",
          "oauth_refresh_token": "4222424241628298228222",
          "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": true,
          "notify_on_weekly_campaign_performance_reports": false,
          "notify_on_call_activities": true,
          "can_login_via_platform": true
        }
      ],
      "default_creative_id_from_network": "222",
      "oauth_refresh_token": "7464644784457575757494930303",
      "custom_data": {
        "channel": "Online lead"
      }
    }
    ```
  </Accordion>

  <Accordion title="Delete an Advertiser" icon={<MethodTag method="delete" path="/advertisers/<advertiser_id>"/>}>
    #### Examples

    Delete a single advertiser

    Endpoint:

    `https://invoca.net/api/2019-05-01/<network_id>/advertisers/cFUyYnFHy.json`

    Format: application/json

    Response Code: 200

    Response Body:

    ```json theme={null}
    {
    }
    ```
  </Accordion>

  <Accordion title="Create an Advertiser" icon={<MethodTag method="post" path="/advertisers"/>}>
    #### Examples

    Create an advertiser with users

    Endpoint:

    `https://invoca.net/api/2019-05-01/<network_id>/advertisers.json`

    Format: application/json

    Request Body:

    ```json theme={null}
    {
      "name": "NFL Tickets Exchange",
      "id_from_network": "cFUyYnFHy",
      "oauth_refresh_token": "7464644784457575757494930303",
      "approval_status": "Approved",
      "web_integration_phone_number": "8004377950",
      "default_creative_id_from_network": "222",
      "users": [
        {
          "id_from_network": "549494858585cFUyYnFHyiYA42TrpM",
          "email_settings": [
            { "email_address": "chris@nfltix.com", "use_for_notifications": true }
          ],
          "first_name": "Chris",
          "last_name": "Dean",
          "contact_phone_number": "805-555-5555",
          "oauth_refresh_token": "556588585858585858585858858",
          "role": "Manager",
          "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": true,
          "notify_on_weekly_campaign_performance_reports": false,
          "notify_on_call_activities": true
        },
        {
          "id_from_network": "694940505055cFUyYnFHyiYA42TrpM",
          "email_settings": [
            { "email_address": "jim@nfltix.com", "use_for_notifications": true }
          ],
          "first_name": "Jim",
          "last_name": "Williams",
          "contact_phone_number": "2135555555",
          "oauth_refresh_token": "4222424241628298228222",
          "role": "Observer",
          "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": true,
          "notify_on_weekly_campaign_performance_reports": false,
          "notify_on_call_activities": true
        }
      ],
      "sites": [
        {
          "id_from_network": "315",
          "name": "315.blog.com"
        },
        {
          "id_from_network": "996",
          "name": "996.blog.com"
        }
      ],
      "custom_data": {
        "channel": "Offline lead"
      }
    }
    ```

    Response Body:

    Same as a GET response, includes all the advertiser properties.
  </Accordion>

  <Accordion title="Update an Advertiser" icon={<MethodTag method="put" path="/advertisers/<advertiser_id>"/>}>
    #### Examples

    Update a user from advertiser

    Endpoint:

    `https://invoca.net/api/2019-05-01/<network_id>/advertisers/cFUyYnFHy.json`

    Format: application/json

    Request Body:

    ```json theme={null}
    {
      "name": "NFL Tickets Exchange",
      "oauth_refresh_token": "7464644784457575757494930303",
      "approval_status": "Approved",
      "web_integration_phone_number": "8004377950",
      "default_creative_id_from_network": "222",
      "users": [
        {
          "id_from_network": "549494858585cFUyYnFHyiYA42TrpM",
          "email_settings": [
            { "email_address": "chris@nfltix.com", "use_for_notifications": true }
          ],
          "first_name": "Chris",
          "last_name": "Dean",
          "contact_phone_number": "805-555-5555",
          "oauth_refresh_token": "556588585858585858585858858",
          "role": "Manager",
          "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": true,
          "notify_on_weekly_campaign_performance_reports": false,
          "notify_on_call_activities": true
        }
      ],
      "sites": [
        {
          "id_from_network": "315",
          "name": "315.blog.com"
        }
      ],
      "custom_data": {
        "channel": "Offline lead"
      }
    }
    ```

    Response Body:

    Same as a GET response, includes all the advertiser properties.
  </Accordion>
</AccordionGroup>