> ## Documentation Index > Fetch the complete documentation index at: https://docs.inboxapp.com/llms.txt > Use this file to discover all available pages before exploring further. # Create import job > Create a new import job to add leads to the campaign from various sources. The job runs asynchronously in the background — poll the job status endpoint to track progress. ## OpenAPI ````yaml post /campaigns/{campaignId}/import-jobs openapi: 3.1.1 info: title: Inbox API version: 1.0.0 description: >+ The Inbox API gives you full access to manage the following entities in your team: - **Threads**: DM conversations on X - **Account links**: X accounts connected to your team - **Members**: users who can access the team - **Prospects**: external profiles on X - **Tags**: labels for prospects - **Statuses**: pipeline statuses for prospects - **Lists**: collections of leads with custom columns and import jobs - **Campaigns**: automated multi-step DM sequences ## A quick note on IDs Inbox stores two types of IDs for objects that relate to X: - `id` — The Inbox ID, which is the ID of the Inbox object - `platformId` — The original X 'platform' ID, which is the ID of the X user, conversation, etc. Throughout the API, you'll see instances where multiple IDs are present. `platformId` is always the original X ID. ## Helpful X URLs You can use platform IDs to construct direct links to X: - **User profile**: `https://x.com/i/user/{platformId}` — This is the most reliable way to link to a user since it uses their immutable ID rather than their username, which can change. - **User by username**: `https://x.com/{username}` — Note that usernames can change, so this link may break if the user updates their handle. - **Tweet/Post**: `https://x.com/anyusername/status/{tweetId}` — The username in the URL is ignored by X; only the tweet ID matters. You can use any string in place of the username and the link will still work. - **DM conversation**: `https://x.com/i/chat/{conversationPlatformId}` — The conversation ID is formatted as `{smallerUserId}:{largerUserId}`, where the two participant user IDs are sorted numerically (smaller ID first). ## Encoding objects and arrays in query params Inbox's API uses bracket notation to denote objects and arrays. ### Objects For an endpoint that accepts a `cursor` parameter for instance, with the cursor object being ```json { id: "l44e15irdq4db30i77cgphhx", timestamp: "2025-11-10T18:03:16.000Z" } ``` The URL search params would be encoded as: ```txt ?cursor[id]=l44e15irdq4db30i77cgphhx&cursor[timestamp]=2025-11-10T18:03:16.000Z ``` ### Arrays For an endpoint that accepts an `ids` parameter for instance, with the value being ```json ["1", "2", "3"] ``` there are three options: 1. Repeat the parameter for each value: ```txt ?ids=1&ids=2&ids=3 ``` 2. Append `[]` to explicitly denote an array (useful if there's only one value): ```txt ?ids[]=1&ids[]=2&ids[]=3 ``` 3. Append `[number]` to denote the array index. This option is the most flexible and allows for reordering and skipping values: ```txt ?ids[0]=1&ids[1]=2&ids[2]=3 ``` summary: >- The Inbox API gives you full access to manage the following entities in your team. servers: - url: https://inboxapp.com/api/v1 security: [] tags: - name: Teams description: >- Teams are shared workspace for members to view and manage account links, tags, statuses, campaigns, conversations, and more. - name: Threads description: >- Threads represent conversations between an account linked to your team and a prospect on Twitter. - name: Messages description: |- Messages are the individual messages sent in a thread. - name: Account Links description: |- Account links represent X accounts connected to your team. - name: Members description: |- Members are Inbox users who can access the team. - name: Prospects description: |- Prospects represent external profiles on X. - name: Tags description: |- Tags are labels for prospects. - name: Statuses description: >- Statuses are used to track the deal stage or any fixed state for a prospect. - name: Colors description: >- Get predefined color options that can be used when creating or updating tags and statuses. - name: Lists description: >- Lists are collections of leads that you can organize, filter, and use as targeting sources for campaigns. - name: List columns description: >- Custom columns defined on a list. Each column stores a text value per lead and can be used as merge variables in campaign messages. - name: Leads description: >- Leads are prospects that belong to a list. Each lead has the full prospect profile, CRM context (tags, status, notes), and list-specific custom column data. - name: Import jobs description: >- Import jobs populate lists from various sources including CSV files, X followers, tweet engagements, and X lists. Poll the job status endpoint to track progress. - name: Campaigns description: >- Campaigns are automated multi-step DM sequences sent to leads via your linked X accounts. A campaign pulls its leads from your existing lists using **lead rules** — attach lists to automatically sync leads into the campaign, and optionally exclude lists (e.g. a "Do Not Contact" list) to avoid messaging certain people. Leads can also be added directly or imported in bulk. Each campaign has a **sequence** of steps — messages, delays, and tweet interactions — that run for every lead. Messages support variables for personalization: use the built-in `first-name` variable or create **custom columns** on the campaign to store per-lead data like company name or role. **Automations** let you trigger actions when certain events occur, such as applying a tag or setting a status when a prospect replies. Configure a sending schedule and hourly message rate, then enable the campaign to start sending. paths: /campaigns/{campaignId}/import-jobs: post: tags: - Campaigns summary: Create import job description: >- Create a new import job to add leads to the campaign from various sources. The job runs asynchronously in the background — poll the job status endpoint to track progress. operationId: campaigns.campaign.importJobs.create parameters: - name: campaignId in: path required: true schema: type: string pattern: ^[0-9a-z]+$ description: The ID of the campaign to import leads into. requestBody: required: true content: application/json: schema: type: object properties: data: anyOf: - type: object properties: type: const: csv content: type: string maxLength: 4194304 description: >- Base64-encoded CSV file content. Maximum 3 MB after decoding. fileName: type: string minLength: 1 description: Original file name of the CSV. examples: - leads.csv columnMapping: type: array items: type: object properties: csvHeader: type: string description: The header name from the CSV file. examples: - Full Name targetColumnId: type: string minLength: 1 description: >- The ID of the column to map this CSV header to. The column must already exist. required: - csvHeader - targetColumnId description: >- Mapping of CSV headers to columns. Columns must be created beforehand via the columns API. mergeStrategy: enum: - overwrite - keep-existing description: >- How to handle conflicts when a lead already exists. 'overwrite' replaces existing column data, 'keep-existing' preserves it. examples: - overwrite required: - type - content - fileName title: CSV file import - type: object properties: type: const: plainText content: type: string maxLength: 4194304 description: >- Base64-encoded plain text file content. Each line should contain a valid user ID or username. Maximum 3 MB after decoding. fileName: type: string minLength: 1 description: Original file name of the text file. examples: - usernames.txt required: - type - content - fileName title: Plain text file import - type: object properties: type: const: followers platform: enum: - twitter description: >- The platform the identifiers belong to. Currently only 'twitter' is supported. examples: - twitter default: twitter platformId: type: string minLength: 1 description: The platform user ID whose followers to import. examples: - '44196397' required: - type - platformId title: Import followers - type: object properties: type: const: following platform: enum: - twitter description: >- The platform the identifiers belong to. Currently only 'twitter' is supported. examples: - twitter default: twitter platformId: type: string minLength: 1 description: The platform user ID whose following list to import. examples: - '44196397' required: - type - platformId title: Import following - type: object properties: type: const: likes tweetId: type: string minLength: 1 description: The tweet ID whose likers to import. examples: - '1897403404901576970' required: - type - tweetId title: Import tweet likes - type: object properties: type: const: retweets tweetId: type: string minLength: 1 description: The tweet ID whose retweeters to import. examples: - '1897403404901576970' required: - type - tweetId title: Import retweets - type: object properties: type: const: quoteTweets tweetId: type: string minLength: 1 description: The tweet ID whose quote tweeters to import. examples: - '1897403404901576970' required: - type - tweetId title: Import quote tweets - type: object properties: type: const: replies tweetId: type: string minLength: 1 description: The tweet ID whose repliers to import. examples: - '1897403404901576970' required: - type - tweetId title: Import replies - type: object properties: type: const: listMembers listId: type: string minLength: 1 description: The X list ID whose members to import. examples: - '1580533571994877954' required: - type - listId title: Import X list members - type: object properties: type: const: listFollowers listId: type: string minLength: 1 description: The X list ID whose followers to import. examples: - '1580533571994877954' required: - type - listId title: Import X list followers - type: object properties: type: const: list sourceListIds: type: array minItems: 1 items: type: string pattern: ^[0-9a-z]+$ description: >- IDs of the Inbox lists to import leads from. Leads from all specified lists are copied into the target list. examples: - - l44e15irdq4db30i77cgphhx columnMappings: type: object propertyNames: type: string additionalProperties: type: string description: >- Maps source column IDs to target column IDs. Only needed for custom columns — profile data is copied automatically. Columns must already exist on the target. Unmapped columns are ignored. examples: - custom_q5cktl47a6pqa74eu06fz89v: custom_m8r2xj93hd5bk0atcw7oe4fp required: - type - sourceListIds title: Import from list - type: object properties: type: const: campaign campaignId: type: string pattern: ^[0-9a-z]+$ description: >- The ID of the campaign to import leads from. Copies leads from the campaign's internal list into the target. examples: - usdjpdql3f90seqk13rwuo7z columnMappings: type: object propertyNames: type: string additionalProperties: type: string description: >- Maps campaign column IDs to target column IDs. Only needed for custom columns — profile data is copied automatically. Columns must already exist on the target. Unmapped columns are ignored. examples: - custom_q5cktl47a6pqa74eu06fz89v: custom_m8r2xj93hd5bk0atcw7oe4fp required: - type - campaignId title: Import from campaign description: >- Import configuration. The type field determines which import source is used and what additional fields are required. required: - data responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ImportJob' components: schemas: ImportJob: type: object properties: id: type: string pattern: ^[0-9a-z]+$ description: Unique identifier for the import job. examples: - l44e15irdq4db30i77cgphhx type: type: string description: The type of importer used for this job. examples: - csv - followers - likes status: enum: - queued - starting - running - paused - completed - failed - canceled description: >- Current status of the import job. 'queued' means the job is waiting for a slot. 'starting' means a slot has been acquired and execution is about to begin. examples: - running - completed totalCount: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' description: Total number of items to import, if known. examples: - 1500 processedCount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Number of items processed so far. examples: - 750 addedCount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Number of leads successfully added. examples: - 700 skippedCount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Number of leads skipped (already exist). examples: - 45 failedCount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Number of leads that failed to import. examples: - 5 error: anyOf: - type: string - type: 'null' description: Error message if the job failed. examples: - Rate limit exceeded createdAt: type: string format: date-time description: When the import job was created. examples: - '2025-01-15T10:30:00.000Z' updatedAt: anyOf: - type: string format: date-time - type: 'null' description: When the import job was last updated. examples: - '2025-01-16T08:00:00.000Z' completedAt: anyOf: - type: string format: date-time - type: 'null' description: When the import job completed. examples: - '2025-01-16T08:05:00.000Z' required: - id - type - status - totalCount - processedCount - addedCount - skippedCount - failedCount - error - createdAt - updatedAt - completedAt ````