---
title: "Create import"
method: POST
path: "/topics/{topicId}/imports"
tags: ["Data Import"]
---

# Create import

`POST /topics/{topicId}/imports`

## Request

- Base URL: `https://api.youscan.io/api/external`
- URL: `https://api.youscan.io/api/external/topics/{topicId}/imports`
- Auth: one of:
  - API key in header `X-API-KEY`
  - API key in query parameter `apiKey`
- TypeScript: <https://skmtc.dev/youscan/apis/youscan-api/docs/topics/:topicId/imports/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a new data import job to import mentions into a topic.

Maximum 100,000 mentions per import.
If items contain a large amount of data (such as lengthy text content), you may receive
a 413 (Content Too Large) error. In this case, try splitting your batch into smaller ones.

**Each mention must have:**
- A valid URL (required) — must be an absolute HTTP or HTTPS URL. If you want to import an item
  without a URL, you should still create a fake unique-per-topic URL (https://mysite.com/1)
- A published date (required) — cannot be empty
- At least one content field: title, text, or imageUrl

**Processing:**
- Mentions are processed asynchronously after the import is created
- Use the Get Import Status endpoint to track progress
- Failed mentions can be retrieved using the Get Import Errors endpoint
- Duplicate mentions (same URL) will be rejected with error code "Duplicate"

## Path parameters

- `topicId` integer, required

## Request body

- object
  - `name` string: Name for this import batch.
  - `mentions` ImportMention[], required: List of mentions to import.
    - `url` string, required: Direct URL to the mention. Must be an absolute HTTP or HTTPS URL, unique per topic.
    - `published` string, date-time, required: Date when the mention was published (ISO 8601 format).
    - `text` string: Main text content of the mention.
    - `title` string: Title of the mention.
    - `postId` string: Unique identifier of the post.
    - `parentPostId` string: ID of the parent post (for comments/replies).
    - `discussionId` string: ID of the discussion thread.
    - `originId` string: Original source identifier.
    - `source` string: Source domain (e.g. "example.com"). Extracted from the URL if not provided.
    - `postType` 'Post' | 'Comment' | 'Repost': Type of post. Default - "Post" if not provided or invalid.
    - `sourceType` 'Social' | 'News' | 'Blog' | 'Forum' | 'Reviews': Type of source. Default - "Social" if not provided or invalid.
    - `contentTypes` string[]: Types of content in the mention.
    - `tagIds` integer[]: List of tag IDs to apply to the mention. Use the List Tags endpoint to get available tag IDs for the topic. Duplicate IDs are ignored.
    - `subcategoryIds` integer[]: List of subcategory IDs to assign to the mention. Requires the Space Categories feature. Use the List Categories endpoint to get available subcategory IDs.
    - `sourceSpecificFormat` 'InstagramReels' | 'InstagramStories' | 'PinterestStoryPins' | 'YouTubeShorts' | 'FacebookReels' | 'FacebookStories' | 'TikTokPhoto' | 'TwitterNote' | 'YouTubeLive' | 'FacebookLive' | 'TwitchLive' | 'TwitterCommunityNote': Source-specific format of the post. Should be omitted in most cases.
    - `author` ImportProfile
      - `profileId` string: Unique identifier of the profile.
      - `name` string: Display name.
      - `nickname` string: Username/handle.
      - `description` string: Profile description/bio.
      - `url` string: Profile URL.
      - `avatarUrl` string: Avatar image URL.
      - `subscribers` integer: Number of subscribers/followers.
      - `gender` 'M' | 'F' | 'Community': Gender. Use "Community" to mark non-person profiles (like a Facebook group or channel).
      - `isVerified` boolean: Verification status.
      - `geo` ImportGeo
        - `countryCode` string: ISO 2-letter country code (e.g. "US").
        - `country` string: Country name.
        - `city` string: City name.
    - `channel` ImportProfile
      - `profileId` string: Unique identifier of the profile.
      - `name` string: Display name.
      - `nickname` string: Username/handle.
      - `description` string: Profile description/bio.
      - `url` string: Profile URL.
      - `avatarUrl` string: Avatar image URL.
      - `subscribers` integer: Number of subscribers/followers.
      - `gender` 'M' | 'F' | 'Community': Gender. Use "Community" to mark non-person profiles (like a Facebook group or channel).
      - `isVerified` boolean: Verification status.
      - `geo` ImportGeo
        - `countryCode` string: ISO 2-letter country code (e.g. "US").
        - `country` string: Country name.
        - `city` string: City name.
    - `engagement` ImportEngagement
      - `likes` integer
      - `comments` integer
      - `shares` integer
      - `views` integer
      - `reactions` integer: Total reactions.
      - `reach` integer: Potential reach.
      - `impressions` integer
      - `saves` integer
    - `mentionGeo` ImportGeo
      - `countryCode` string: ISO 2-letter country code (e.g. "US").
      - `country` string: Country name.
      - `city` string: City name.
    - `imageUrl` string: URL of the main image.
    - `rating` number: Rating value (0-5).
    - `language` string: Language code (e.g. "eng").

## Response `201`

Import created.

- object
  - `importId` integer: Unique identifier for this import.
  - `name` string, nullable: Name of the import.
  - `totalReceived` integer: Number of mentions received.
  - `status` string: Current status of the import.

## Other responses

- `400`: The request is invalid.
- `401`: The API key is missing or invalid.
- `404`: Topic not found or you don't have access to it.
- `413`: Request payload is too large. Split your batch into smaller ones.

---

[API](https://skmtc.dev/youscan/apis/youscan-api.md) - [All operations](https://skmtc.dev/youscan/apis/youscan-api/llms.txt) - [OpenAPI document](https://skmtc.dev/youscan/apis/youscan-api/revisions/f5bef260f153?raw)