> ## Documentation Index
> Fetch the complete documentation index at: https://plai-a079b342.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Contact List Audience

> This endpoint allows you to create a custom audience by uploading a CSV file containing user data (such as emails, phone numbers, or other identifiers). The uploaded data is processed and matched against platform records to build a targeted audience for advertising purposes.

## Request Body

<Note>
  The request body for this endpoint should be sent as `multipart/form-data`.
  The following fields are expected:
</Note>

<ParamField body="userId" type="string" required>
  User ID, If not already created, make a user on [create user
  page](/api-reference/endpoint/auth/create_user) first. If already created,
  retrieve the user ID from [get profile
  page](/api-reference/endpoint/auth/get_profile).
</ParamField>

<ParamField body="audienceName" type="string" required>
  The name of the audience you are creating. This name will be displayed in
  your Facebook Ads account.
</ParamField>

<ParamField body="csvFile" type="file" required>
  <Card title="Download Sample CSV" icon="download" href="https://business.facebook.com/images/ads/signals/example_files/example_value_based_audience_file.csv">
    Sample CSV
  </Card>

  <Note>
    Make sure to follow csv guidelines from [here](https://www.facebook.com/business/help/2082575038703844?id=2469097953376494)
  </Note>

  Audience Csv. Ensure the file is in CSV format.
</ParamField>

<ParamField body="mode" type="string" default="create">
  Operation mode for the audience : `create` (default): Create a new audience.
  `append`: Add more entries to an existing audience. `replace`: Replace all
  entries in an existing audience. `remove`: Remove entries from an existing
  audience Required when modifying an existing audience.
</ParamField>

<ParamField body="audienceId" type="string">
  The ID of the existing audience to modify. Required when mode is `append`,
  `replace`, or `remove`.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates that the HTTP response was successful (status code 200 OK).
</ResponseField>

<ResponseField name="results" type="object">
  <Expandable title="Audience Results">
    <ResponseField name="success" type="boolean">
      Indicates whether the specific operation or API action was successful.
    </ResponseField>

    <ResponseField name="audienceId" type="string">
      Unique identifier for the audience
    </ResponseField>

    <ResponseField name="audienceName" type="string">
      Name of the audience
    </ResponseField>

    <ResponseField name="invalid_entry_samples" type="object">
      <Note>Empty object when no invalid entries exist</Note>
    </ResponseField>

    <ResponseField name="num_invalid_entries" type="number">
      Count of invalid entries in the audience
    </ResponseField>

    <ResponseField name="num_received" type="number">
      Total number of entries received
    </ResponseField>

    <ResponseField name="session_id" type="string">
      Processing session identifier
    </ResponseField>

    <ResponseField name="error" type="string">
      Error string if something went wrong
    </ResponseField>
  </Expandable>
</ResponseField>