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

# Create Persona

> Create a persona from job titles, industries, locations and company sizes

`name` and at least one entry in `job_titles` are required. The Sales Navigator URL returned in `sales_nav_url` is built from the filters you send.

Set `ai_expand_job_titles` to `true` to expand `job_titles` with AI-generated variations (other seniority levels and languages); the suggested exclusions are added to `excluded_job_titles`. Get location IDs from the [Location IDs endpoint](/api-reference/endpoints/miscellaneous/location-ids).


## OpenAPI

````yaml POST /personas
openapi: 3.0.1
info:
  title: Pipecorn Personas API
  description: Pipecorn Personas API
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://app.pipecorn.com/api/v2/
security:
  - defaultApiKey: []
paths:
  /personas:
    post:
      summary: Create a persona
      description: >-
        Creates a persona from structured filters. The Sales Navigator URL is
        derived from the filters.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - job_titles
              properties:
                name:
                  type: string
                  description: Name of the persona
                  example: VP Engineering France
                description:
                  type: string
                  description: Free-text description of the persona
                  example: Engineering leaders at French SaaS scale-ups
                job_titles:
                  type: array
                  items:
                    type: string
                  description: Job titles to include. At least one is required
                  example:
                    - VP of Engineering
                    - CTO
                excluded_job_titles:
                  type: array
                  items:
                    type: string
                  description: Job titles to exclude
                  example:
                    - Assistant
                    - Intern
                ai_expand_job_titles:
                  type: boolean
                  default: false
                  description: >-
                    When `true`, the titles in `job_titles` are expanded with AI
                    into variations (other seniority levels and languages, based
                    on your agent language preferences). Suggested exclusions
                    are added to `excluded_job_titles`.
                included_industries:
                  type: array
                  items:
                    type: string
                  description: LinkedIn industry IDs to include
                  example:
                    - '4'
                excluded_industries:
                  type: array
                  items:
                    type: string
                  description: LinkedIn industry IDs to exclude
                  example: []
                included_locations:
                  type: array
                  items:
                    type: string
                  description: Location IDs to include (see the Location IDs endpoint)
                  example:
                    - '105015875'
                excluded_locations:
                  type: array
                  items:
                    type: string
                  description: Location IDs to exclude
                  example: []
                company_size:
                  type: array
                  items:
                    type: string
                    enum:
                      - Self-employed
                      - 1-10
                      - 11-50
                      - 51-200
                      - 201-500
                      - 501-1000
                      - 1001-5000
                      - 5001-10000
                      - 10001+
                  description: >-
                    Company headcount ranges. The LinkedIn size codes `A`–`I`
                    are also accepted for older integrations, and are returned
                    as sent.
                  example:
                    - 51-200
                    - 201-500
            example:
              name: VP Engineering France
              job_titles:
                - VP of Engineering
                - CTO
              excluded_job_titles:
                - Assistant
              included_locations:
                - '105015875'
              company_size:
                - 51-200
                - 201-500
      responses:
        '201':
          description: Persona created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Persona'
              example:
                uuid: 8e1dcba0-f0bb-4071-99fc-f18ba6559ccc
                name: VP Engineering France
                description: Engineering leaders at French SaaS scale-ups
                included_job_titles:
                  - VP of Engineering
                  - CTO
                excluded_job_titles:
                  - Assistant
                included_industries:
                  - '4'
                excluded_industries: []
                included_locations:
                  - '105015875'
                excluded_locations: []
                company_size:
                  - 51-200
                  - 201-500
                sales_nav_url: https://www.linkedin.com/sales/search/people?query=...
                created_at: '2025-01-03T17:35:33.073Z'
                updated_at: '2025-01-03T17:35:33.073Z'
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
        '400':
          description: The request body is not a JSON object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_json:
                  summary: Invalid JSON
                  value:
                    error: Invalid JSON
                not_object:
                  summary: Request body must be a JSON object
                  value:
                    error: Request body must be a JSON object
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missing_key:
                  summary: No API key present
                  value:
                    error: No API key present
                invalid_key:
                  summary: Invalid API key
                  value:
                    error: Invalid API key
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
        '422':
          description: >-
            Validation failed. `job_titles`, `excluded_job_titles`,
            `included_industries`, `excluded_industries`, `included_locations`,
            `excluded_locations` and `company_size` must be arrays; a failed
            save returns the list of validation messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                name_missing:
                  summary: name is required
                  value:
                    error: name is required
                no_job_title:
                  summary: At least one job_title is required
                  value:
                    error: At least one job_title is required
                not_array:
                  summary: job_titles must be an array
                  value:
                    error: job_titles must be an array
        '429':
          description: Rate limit exceeded (your plan's per-minute limit)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Rate limit exceeded. Please wait before retrying.
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        A unique value you generate per operation, such as a UUID. Retrying with
        the same key and the same body returns the stored response instead of
        running the request again, so a retry after a timeout never charges
        twice. Successful responses are kept for 24 hours; a failed request is
        not stored and can be retried with the same key.
      schema:
        type: string
        maxLength: 255
        example: 4f1c2e9a-8a7d-4c1b-9f63-2d6e0b5a7c11
  schemas:
    Persona:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          description: Unique identifier of the persona
          example: 8e1dcba0-f0bb-4071-99fc-f18ba6559ccc
        name:
          type: string
          description: Name of the persona
          example: VP Engineering France
        description:
          type: string
          nullable: true
          description: Free-text description
          example: Engineering leaders at French SaaS scale-ups
        included_job_titles:
          type: array
          items:
            type: string
          description: Job titles to include
          example:
            - VP of Engineering
            - CTO
        excluded_job_titles:
          type: array
          items:
            type: string
          description: Job titles to exclude
          example:
            - Assistant
        included_industries:
          type: array
          items:
            type: string
          description: LinkedIn industry IDs to include
          example:
            - '4'
        excluded_industries:
          type: array
          items:
            type: string
          description: LinkedIn industry IDs to exclude
          example: []
        included_locations:
          type: array
          items:
            type: string
          description: Location IDs to include
          example:
            - '105015875'
        excluded_locations:
          type: array
          items:
            type: string
          description: Location IDs to exclude
          example: []
        company_size:
          type: array
          items:
            type: string
          description: Company size ranges
          example:
            - 51-200
            - 201-500
        sales_nav_url:
          type: string
          nullable: true
          description: Sales Navigator search URL derived from the filters
          example: https://www.linkedin.com/sales/search/people?query=...
        created_at:
          type: string
          format: date-time
          description: The creation date of the persona
          example: '2025-01-03T17:35:33.073Z'
        updated_at:
          type: string
          format: date-time
          description: The last modified date of the persona
          example: '2025-01-03T17:35:33.073Z'
    Error:
      required:
        - error
      type: object
      properties:
        error:
          description: >-
            Human-readable error message. A few validation errors return a list
            of messages instead of a single string.
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        message:
          type: string
          description: >-
            Longer explanation, sent by validators that add context. Such errors
            may also carry extra top-level keys like `valid_values` or
            `example`.
        details:
          type: string
          description: >-
            Parser message, sent with `"Invalid JSON format in request body"`
            when the request body is not valid JSON.
  headers:
    RateLimit-Limit:
      description: >-
        Requests allowed per minute on your plan for this group of endpoints.
        Absent for unlimited accounts and on endpoints exempt from the plan
        limit.
      schema:
        type: integer
        example: 100
    RateLimit-Remaining:
      description: Requests left in the current one-minute window.
      schema:
        type: integer
        example: 97
    RateLimit-Reset:
      description: >-
        Seconds until the current window resets and `RateLimit-Remaining` is
        back to `RateLimit-Limit`.
      schema:
        type: integer
        example: 42
    Idempotent-Replayed:
      description: >-
        `true` when this response is a replay of an earlier request sent with
        the same `Idempotency-Key`. Nothing was run or charged again.
      schema:
        type: string
        enum:
          - 'true'
    Retry-After:
      description: >-
        Seconds to wait before retrying. Sent when the plan limit or a request
        still in progress caused the error.
      schema:
        type: integer
        example: 42
  responses:
    IdempotencyConflict:
      description: >-
        A request with this `Idempotency-Key` is still being processed. Wait for
        the `Retry-After` delay and retry with the same key.
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              code:
                type: string
                enum:
                  - idempotency_key_in_use
          example:
            error: A request with this Idempotency-Key is still being processed
            code: idempotency_key_in_use
  securitySchemes:
    defaultApiKey:
      type: apiKey
      in: header
      description: Your API key
      name: X-API-KEY

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.