Influship Creator Emails API

openapi: 3.2.0
info:
  title: Influship Creator Emails API
  version: 1.0.0
  description: 'Public API for creator search, profile lookup, and campaign-fit analysis.


    ## Authentication


    Send your API key in the `X-API-Key` header on every authenticated request.


    ```bash

    curl -H "X-API-Key: your_api_key" https://api.influship.com/v1/creators/autocomplete?q=fitness

    ```


    ## Billing and Rate Limits


    The API uses credit-based billing and credit-based rate limits.


    - every endpoint has a credit cost

    - successful responses include `X-Credits-Charged` and `X-Credits-Features`

    - rate limits are enforced with per-minute and per-hour credit budgets

    - rate limit state is returned in the `RateLimit-*` headers


    Account-specific credit budgets take precedence over tier defaults. Use the returned

    `RateLimit-Limit-Minute` and `RateLimit-Limit-Hour` headers to read your effective budgets.


    ## Agentic Payments


    Use `https://api.influship.com/openapi.json` to discover endpoints that accept x402 v2 or MPP payments without an API key. It includes `402` payment challenges and `x-payment-info` metadata for the available payment methods.


    ## Pagination


    List endpoints use cursor pagination.


    - send `limit` to control page size

    - use `next_cursor` from the response to fetch the next page

    - stop when `has_more` is `false`


    Search has one special rule:


    - `POST /v1/search` creates a persisted search session

    - `GET /v1/search/{id}` paginates that session for free

    - free pagination is capped by the original search `limit`


    ## Errors


    Errors use a consistent shape:


    ```json

    {

    "error": {

    "code": "rate_limit_exceeded",

    "message": "Rate limit exceeded (per minute)"

    }

    }

    ```


    See each operation for exact request and response schemas.'
  contact:
    name: Influship Support
    email: support@influship.com
  license:
    name: Proprietary
    url: https://influship.com/terms
  x-guidance: 'Use the operation requestBody and query/path parameter schemas exactly as declared. Paid operations return HTTP 402 with x402 v2 and MPP payment challenges when called without payment; retry the same request with either x402 PAYMENT-SIGNATURE credentials (X-PAYMENT is also accepted for compatibility) or MPP Authorization: Payment credentials.'
servers:
- url: https://api.influship.com
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: Creator Emails
  description: Look up known creator email addresses by creator ID or social username. Empty or unresolved results are not billable.
paths:
  /v1/creator-emails/lookup:
    post:
      operationId: lookupCreatorEmails
      summary: Lookup Creator Emails
      tags:
      - Creator Emails
      description: 'Look up known email addresses for creators by creator ID or social username.


        **Billing behavior:**

        - Charged only for unique resolved creators with at least one returned email

        - Empty and unresolved results are not billable

        - Returns validation status so unvalidated emails are explicit


        **Pricing**: 5 credits per creator with at least one returned email ($0.05)'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatorEmailsLookupRequest'
        description: Creator email lookup request
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatorEmailsLookupResponse'
        '400':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '402':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiCreditError402'
        '403':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '429':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429'
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
        '503':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error503'
components:
  schemas:
    ErrorInsufficientCredits:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              const: insufficient_credits
            message:
              type: string
            status_code:
              type: number
              const: 402
            request_id:
              type: string
            details:
              type: object
              propertyNames:
                type: string
              additionalProperties: {}
          required:
          - code
          - message
          additionalProperties: false
      required:
      - error
      additionalProperties: false
      description: Remaining credits cannot cover this request. Add a payment method to continue. Do not retry automatically.
      examples:
      - error:
          code: insufficient_credits
          message: Not enough credits remaining for this search. Add a payment method to continue.
          details:
            remaining: 10
            required: 75
            add_payment_method: true
    CreatorEmailLookupById:
      type: object
      properties:
        creator_id:
          type: string
          format: uuid
          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
          description: Creator profile ID to look up directly
          example: 123e4567-e89b-12d3-a456-426614174000
      required:
      - creator_id
      description: Creator email lookup input by creator ID
    CreatorEmailItem:
      type: object
      properties:
        email:
          type: string
          minLength: 1
          description: Email address as stored, preserving original casing
          example: hello@example.com
        status:
          $ref: '#/components/schemas/CreatorEmailStatus'
        confidence:
          anyOf:
          - type: number
            minimum: 0
            maximum: 1
          - type: 'null'
          description: Nullable confidence score for the email
          example: 0.72
        is_primary:
          type: boolean
          description: Whether this is the primary email for the creator
          example: false
        validated_at:
          anyOf:
          - type: string
            format: date-time
            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
          - type: 'null'
          description: When the email was last validated, if known
          example: null
        first_seen_at:
          type: string
          format: date-time
          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
          description: When Influship first observed this email
          example: '2026-05-01T00:00:00Z'
        last_seen_at:
          type: string
          format: date-time
          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
          description: When Influship most recently observed this email
          example: '2026-05-02T00:00:00Z'
      required:
      - email
      - status
      - confidence
      - is_primary
      - validated_at
      - first_seen_at
      - last_seen_at
      additionalProperties: false
      description: API-visible creator email
    Platform:
      type: string
      enum:
      - instagram
      description: Social media platform
      example: instagram
    CreatorEmailsLookupRequest:
      type: object
      properties:
        creators:
          minItems: 1
          maxItems: 100
          type: array
          items:
            $ref: '#/components/schemas/CreatorEmailLookupInput'
          description: Creator lookups to resolve. Response rows preserve this input order.
      required:
      - creators
      description: Creator email lookup request
    Error401:
      description: Authentication error response
      examples:
      - error:
          code: unauthorized
          message: API key missing or invalid
          request_id: 550e8400-e29b-41d4-a716-446655440000
      $ref: '#/components/schemas/Error'
    CreatorEmailsBilling:
      type: object
      properties:
        billable_results:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: Unique resolved creators with at least one returned email
          example: 1
        credits_charged:
          type: number
          minimum: 0
          description: Preview of credits charged for this lookup
          example: 5
      required:
      - billable_results
      - credits_charged
      additionalProperties: false
      description: Creator email lookup billing summary
    CreatorEmailStatus:
      type: string
      enum:
      - unvalidated
      - valid
      - risky
      - creator_verified
      description: API-visible email validation status
      example: unvalidated
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              description: Machine-readable error code
              $ref: '#/components/schemas/ErrorCode'
            message:
              type: string
              description: Human-readable error message
              example: Request validation failed
            status_code:
              description: HTTP status code repeated for clients that consume the error body
              example: 402
              type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            param:
              description: Parameter that caused the error (if applicable)
              example: query
              type: string
            request_id:
              description: Optional request ID for debugging. Read the X-Request-Id response header when absent.
              example: 550e8400-e29b-41d4-a716-446655440000
              type: string
            details:
              description: Structured error context (e.g., field-level validation issues)
              type: object
              propertyNames:
                type: string
              additionalProperties: {}
          required:
          - code
          - message
          additionalProperties: false
      required:
      - error
      additionalProperties: false
    Error503:
      description: 'Service temporarily unavailable: a live data upstream, or a creator search, match or lookalike request that could not finish in time. Check Retry-After when present and retry with bounded backoff.'
      examples:
      - error:
          code: service_unavailable
          message: Live Instagram data is temporarily unavailable. Please retry shortly.
          request_id: 550e8400-e29b-41d4-a716-446655440000
          details:
            retry_after_seconds: 60
            upstream_error: upstream_rate_limited
      $ref: '#/components/schemas/Error'
    Error403:
      description: Permission error response
      examples:
      - error:
          code: forbidden
          message: Your plan does not include access to this endpoint
          request_id: 550e8400-e29b-41d4-a716-446655440000
      $ref: '#/components/schemas/Error'
    Error429:
      description: Rate limit exceeded response. Check Retry-After header for backoff timing. Also returned (without RateLimit-* headers) when an IP is temporarily blocked after repeated failed authentication attempts.
      examples:
      - error:
          code: rate_limit_exceeded
          message: Rate limit exceeded (per minute)
          request_id: 550e8400-e29b-41d4-a716-446655440000
      - error:
          code: rate_limit_exceeded
          message: Rate limit exceeded (per hour)
          request_id: 550e8400-e29b-41d4-a716-446655440001
      - error:
          code: rate_limit_exceeded
          message: Too many failed authentication attempts. Please try again later.
          request_id: 550e8400-e29b-41d4-a716-446655440002
      $ref: '#/components/schemas/Error'
    CreatorEmailLookupByHandleOutput:
      type: object
      properties:
        platform:
          description: Social platform for handle-based lookup
          $ref: '#/components/schemas/Platform'
        username:
          type: string
          minLength: 1
          maxLength: 100
          description: Social username for handle-based lookup
          example: fitness_coach_jane
      required:
      - platform
      - username
      additionalProperties: false
      description: Creator email lookup input by social handle
    Error400:
      description: Validation error response
      examples:
      - error:
          code: validation_error
          message: 'Invalid value for parameter ''limit'': must be between 1 and 100'
          param: limit
          request_id: 550e8400-e29b-41d4-a716-446655440000
      $ref: '#/components/schemas/Error'
    CreatorEmailsLookupResult:
      type: object
      properties:
        input:
          $ref: '#/components/schemas/CreatorEmailLookupInputOutput'
        creator_id:
          anyOf:
          - type: string
            format: uuid
            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
          - type: 'null'
          description: Resolved creator ID, or null when the input could not be resolved
          example: 123e4567-e89b-12d3-a456-426614174000
        resolved:
          type: boolean
          description: Whether the lookup resolved to a creator profile
          example: true
        emails:
          type: array
          items:
            $ref: '#/components/schemas/CreatorEmailItem'
          description: API-visible emails for the resolved creator. Empty results are not billable.
      required:
      - input
      - creator_id
      - resolved
      - emails
      additionalProperties: false
      description: Creator email lookup result
    ApiCreditError402:
      anyOf:
      - $ref: '#/components/schemas/Error402'
      - $ref: '#/components/schemas/ErrorInsufficientCredits'
      description: Account billing requires attention, or available credits cannot cover this request.
    Error500:
      description: Internal server error response
      examples:
      - error:
          code: internal_error
          message: An unexpected error occurred. Please try again later.
          request_id: 550e8400-e29b-41d4-a716-446655440000
      $ref: '#/components/schemas/Error'
    CreatorEmailLookupByIdOutput:
      type: object
      properties:
        creator_id:
          type: string
          format: uuid
          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
          description: Creator profile ID to look up directly
          example: 123e4567-e89b-12d3-a456-426614174000
      required:
      - creator_id
      additionalProperties: false
      description: Creator email lookup input by creator ID
    CreatorEmailsLookupResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            results:
              type: array
              items:
                $ref: '#/components/schemas/CreatorEmailsLookupResult'
            billing:
              $ref: '#/components/schemas/CreatorEmailsBilling'
          required:
          - results
          - billing
          additionalProperties: false
      required:
      - data
      additionalProperties: false
      description: Creator email lookup response
    CreatorEmailLookupInputOutput:
      anyOf:
      - $ref: '#/components/schemas/CreatorEmailLookupByIdOutput'
      - $ref: '#/components/schemas/CreatorEmailLookupByHandleOutput'
      description: Creator email lookup input by creator ID or social handle
    CreatorEmailLookupByHandle:
      type: object
      properties:
        platform:
          description: Social platform for handle-based lookup
          $ref: '#/components/schemas/Platform'
        username:
          type: string
          minLength: 1
          maxLength: 100
          description: Social username for handle-based lookup
          example: fitness_coach_jane
      required:
      - platform
      - username
      description: Creator email lookup input by social handle
    ErrorCode:
      type: string
      enum:
      - validation_error
      - invalid_parameter
      - missing_parameter
      - unauthorized
      - forbidden
      - payment_required
      - insufficient_credits
      - not_found
      - rate_limit_exceeded
      - quota_exceeded
      - internal_error
      - service_unavailable
      - upstream_contract_broken
      - database_error
      - seed_not_found
      - invalid_seeds
      - seed_resolution_failed
      - lookalike_failed
      - get_profiles_failed
      - post_analysis_failed
      - match_failed
      - scraping_failed
      - transcript_unavailable
      - transcript_not_available
      - transcription_limit_exceeded
      - transcription_unavailable
      description: Machine-readable error code for programmatic handling
      example: validation_error
    Error402:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              const: payment_required
            message:
              type: string
            status_code:
              type: number
              const: 402
            reason_code:
              type: string
              enum:
              - BILLING_SUSPENDED
              - PAYMENT_FAILED
              - PAYMENT_ACTION_REQUIRED
              - DISPUTE_OPENED
              - NO_PAYMENT_METHOD
              - SUBSCRIPTION_REQUIRED
              - NO_BUNDLE_CONFIGURED
              - BUNDLE_EXHAUSTED
            next_step:
              type: string
              enum:
              - update_payment_method
              - complete_authentication
              - contact_support
              - add_payment_method
              - reconnect_connection
              - upgrade_plan
            request_id:
              type: string
            details:
              type: object
              propertyNames:
                type: string
              additionalProperties: {}
          required:
          - code
          - message
          - status_code
          - reason_code
          - next_step
          additionalProperties: false
      required:
      - error
      additionalProperties: false
      description: Payment required response. Returned when account billing or a subscription bundle requires attention.
      examples:
      - error:
          code: payment_required
          message: Payment authentication is required.
          status_code: 402
          reason_code: PAYMENT_ACTION_REQUIRED
          next_step: complete_authentication
          request_id: 550e8400-e29b-41d4-a716-446655440000
    CreatorEmailLookupInput:
      anyOf:
      - $ref: '#/components/schemas/CreatorEmailLookupById'
      - $ref: '#/components/schemas/CreatorEmailLookupByHandle'
      description: Creator email lookup input by creator ID or social handle
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key