Enrich known entities

curl --request POST \
  --url https://api.unif.dev/v1/enrich \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "currency": "USD",
  "period": {
    "preset": "last_30d"
  },
  "fields": [
    "name",
    "categories",
    "metrics.revenue",
    "metrics.units_sold",
    "metrics.revenue_growth_rate"
  ],
  "inputs": [
    {
      "type": "shop",
      "url": "https://www.tiktok.com/shop/glowlab"
    },
    {
      "type": "shop",
      "url": "https://www.tiktok.com/shop/northpeak"
    }
  ]
}
'

import requests

url = "https://api.unif.dev/v1/enrich"

payload = {
    "currency": "USD",
    "period": { "preset": "last_30d" },
    "fields": ["name", "categories", "metrics.revenue", "metrics.units_sold", "metrics.revenue_growth_rate"],
    "inputs": [
        {
            "type": "shop",
            "url": "https://www.tiktok.com/shop/glowlab"
        },
        {
            "type": "shop",
            "url": "https://www.tiktok.com/shop/northpeak"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    currency: 'USD',
    period: {preset: 'last_30d'},
    fields: [
      'name',
      'categories',
      'metrics.revenue',
      'metrics.units_sold',
      'metrics.revenue_growth_rate'
    ],
    inputs: [
      {type: 'shop', url: 'https://www.tiktok.com/shop/glowlab'},
      {type: 'shop', url: 'https://www.tiktok.com/shop/northpeak'}
    ]
  })
};

fetch('https://api.unif.dev/v1/enrich', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unif.dev/v1/enrich",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'currency' => 'USD',
    'period' => [
        'preset' => 'last_30d'
    ],
    'fields' => [
        'name',
        'categories',
        'metrics.revenue',
        'metrics.units_sold',
        'metrics.revenue_growth_rate'
    ],
    'inputs' => [
        [
                'type' => 'shop',
                'url' => 'https://www.tiktok.com/shop/glowlab'
        ],
        [
                'type' => 'shop',
                'url' => 'https://www.tiktok.com/shop/northpeak'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.unif.dev/v1/enrich"

	payload := strings.NewReader("{\n  \"currency\": \"USD\",\n  \"period\": {\n    \"preset\": \"last_30d\"\n  },\n  \"fields\": [\n    \"name\",\n    \"categories\",\n    \"metrics.revenue\",\n    \"metrics.units_sold\",\n    \"metrics.revenue_growth_rate\"\n  ],\n  \"inputs\": [\n    {\n      \"type\": \"shop\",\n      \"url\": \"https://www.tiktok.com/shop/glowlab\"\n    },\n    {\n      \"type\": \"shop\",\n      \"url\": \"https://www.tiktok.com/shop/northpeak\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.unif.dev/v1/enrich")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"currency\": \"USD\",\n  \"period\": {\n    \"preset\": \"last_30d\"\n  },\n  \"fields\": [\n    \"name\",\n    \"categories\",\n    \"metrics.revenue\",\n    \"metrics.units_sold\",\n    \"metrics.revenue_growth_rate\"\n  ],\n  \"inputs\": [\n    {\n      \"type\": \"shop\",\n      \"url\": \"https://www.tiktok.com/shop/glowlab\"\n    },\n    {\n      \"type\": \"shop\",\n      \"url\": \"https://www.tiktok.com/shop/northpeak\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.unif.dev/v1/enrich")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"currency\": \"USD\",\n  \"period\": {\n    \"preset\": \"last_30d\"\n  },\n  \"fields\": [\n    \"name\",\n    \"categories\",\n    \"metrics.revenue\",\n    \"metrics.units_sold\",\n    \"metrics.revenue_growth_rate\"\n  ],\n  \"inputs\": [\n    {\n      \"type\": \"shop\",\n      \"url\": \"https://www.tiktok.com/shop/glowlab\"\n    },\n    {\n      \"type\": \"shop\",\n      \"url\": \"https://www.tiktok.com/shop/northpeak\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "object": "enrich_response",
  "data": [
    {
      "ref": "<string>",
      "status": "enriched",
      "type": "shop",
      "data": {
        "id": "shp_01k3m9x7v2q8r4t6y0b1n5d7fa",
        "object": "shop",
        "channel": "tiktok_shop",
        "market": "US",
        "name": "GlowLab",
        "handle": "glowlab",
        "url": "<string>",
        "logo_url": "<string>",
        "seller_type": "brand",
        "categories": [
          {
            "id": "cat_beauty_personal_care",
            "name": "Beauty & Personal Care",
            "path": [
              "<string>"
            ]
          }
        ],
        "rating": 2.5,
        "reviews_count": 123,
        "products_count": 123,
        "opened_at": "2023-12-25",
        "metrics": {
          "revenue": 123,
          "units_sold": 123,
          "avg_unit_price": 123,
          "revenue_growth_rate": 123,
          "revenue_by_source": {
            "video": 123,
            "live": 123,
            "mall": 123,
            "search": 123
          },
          "products_sold_count": 123,
          "creators_count": 123,
          "videos_count": 123,
          "livestreams_count": 123
        },
        "period": {
          "start": "2023-12-25",
          "end": "2023-12-25",
          "granularity": "day",
          "adjusted": true
        },
        "currency": "<string>",
        "meta": {
          "refreshed_at": "2023-11-07T05:31:56Z",
          "completeness": 0.5,
          "missing_fields": [
            "<string>"
          ]
        }
      },
      "meta": {
        "refreshed_at": "2023-11-07T05:31:56Z",
        "completeness": 0.5,
        "missing_fields": [
          "<string>"
        ]
      }
    }
  ],
  "period": {
    "start": "2023-12-25",
    "end": "2023-12-25",
    "granularity": "day",
    "adjusted": true
  },
  "currency": "<string>",
  "credits_charged": 123
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "filters.revenue.gte must be a non-negative number.",
    "param": "filters.revenue.gte",
    "doc_url": "https://unif.dev/docs/platform/errors#parameter_invalid",
    "request_id": "req_01k3m9x7v2q8r4t6y0b1n5d7fa"
  }
}

{
  "error": {
    "type": "billing_error",
    "code": "insufficient_credits",
    "message": "This request costs 25 credits and 4 remain in the current period.",
    "doc_url": "https://unif.dev/docs/platform/credits",
    "request_id": "req_01k3m9x7v2q8r4t6y0b1n5d7fa"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

POST

https://api.unif.dev/v1

enrich

Enrich known entities

curl --request POST \
  --url https://api.unif.dev/v1/enrich \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "currency": "USD",
  "period": {
    "preset": "last_30d"
  },
  "fields": [
    "name",
    "categories",
    "metrics.revenue",
    "metrics.units_sold",
    "metrics.revenue_growth_rate"
  ],
  "inputs": [
    {
      "type": "shop",
      "url": "https://www.tiktok.com/shop/glowlab"
    },
    {
      "type": "shop",
      "url": "https://www.tiktok.com/shop/northpeak"
    }
  ]
}
'

import requests

url = "https://api.unif.dev/v1/enrich"

payload = {
    "currency": "USD",
    "period": { "preset": "last_30d" },
    "fields": ["name", "categories", "metrics.revenue", "metrics.units_sold", "metrics.revenue_growth_rate"],
    "inputs": [
        {
            "type": "shop",
            "url": "https://www.tiktok.com/shop/glowlab"
        },
        {
            "type": "shop",
            "url": "https://www.tiktok.com/shop/northpeak"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    currency: 'USD',
    period: {preset: 'last_30d'},
    fields: [
      'name',
      'categories',
      'metrics.revenue',
      'metrics.units_sold',
      'metrics.revenue_growth_rate'
    ],
    inputs: [
      {type: 'shop', url: 'https://www.tiktok.com/shop/glowlab'},
      {type: 'shop', url: 'https://www.tiktok.com/shop/northpeak'}
    ]
  })
};

fetch('https://api.unif.dev/v1/enrich', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.unif.dev/v1/enrich",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'currency' => 'USD',
    'period' => [
        'preset' => 'last_30d'
    ],
    'fields' => [
        'name',
        'categories',
        'metrics.revenue',
        'metrics.units_sold',
        'metrics.revenue_growth_rate'
    ],
    'inputs' => [
        [
                'type' => 'shop',
                'url' => 'https://www.tiktok.com/shop/glowlab'
        ],
        [
                'type' => 'shop',
                'url' => 'https://www.tiktok.com/shop/northpeak'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.unif.dev/v1/enrich"

	payload := strings.NewReader("{\n  \"currency\": \"USD\",\n  \"period\": {\n    \"preset\": \"last_30d\"\n  },\n  \"fields\": [\n    \"name\",\n    \"categories\",\n    \"metrics.revenue\",\n    \"metrics.units_sold\",\n    \"metrics.revenue_growth_rate\"\n  ],\n  \"inputs\": [\n    {\n      \"type\": \"shop\",\n      \"url\": \"https://www.tiktok.com/shop/glowlab\"\n    },\n    {\n      \"type\": \"shop\",\n      \"url\": \"https://www.tiktok.com/shop/northpeak\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.unif.dev/v1/enrich")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"currency\": \"USD\",\n  \"period\": {\n    \"preset\": \"last_30d\"\n  },\n  \"fields\": [\n    \"name\",\n    \"categories\",\n    \"metrics.revenue\",\n    \"metrics.units_sold\",\n    \"metrics.revenue_growth_rate\"\n  ],\n  \"inputs\": [\n    {\n      \"type\": \"shop\",\n      \"url\": \"https://www.tiktok.com/shop/glowlab\"\n    },\n    {\n      \"type\": \"shop\",\n      \"url\": \"https://www.tiktok.com/shop/northpeak\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.unif.dev/v1/enrich")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"currency\": \"USD\",\n  \"period\": {\n    \"preset\": \"last_30d\"\n  },\n  \"fields\": [\n    \"name\",\n    \"categories\",\n    \"metrics.revenue\",\n    \"metrics.units_sold\",\n    \"metrics.revenue_growth_rate\"\n  ],\n  \"inputs\": [\n    {\n      \"type\": \"shop\",\n      \"url\": \"https://www.tiktok.com/shop/glowlab\"\n    },\n    {\n      \"type\": \"shop\",\n      \"url\": \"https://www.tiktok.com/shop/northpeak\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "object": "enrich_response",
  "data": [
    {
      "ref": "<string>",
      "status": "enriched",
      "type": "shop",
      "data": {
        "id": "shp_01k3m9x7v2q8r4t6y0b1n5d7fa",
        "object": "shop",
        "channel": "tiktok_shop",
        "market": "US",
        "name": "GlowLab",
        "handle": "glowlab",
        "url": "<string>",
        "logo_url": "<string>",
        "seller_type": "brand",
        "categories": [
          {
            "id": "cat_beauty_personal_care",
            "name": "Beauty & Personal Care",
            "path": [
              "<string>"
            ]
          }
        ],
        "rating": 2.5,
        "reviews_count": 123,
        "products_count": 123,
        "opened_at": "2023-12-25",
        "metrics": {
          "revenue": 123,
          "units_sold": 123,
          "avg_unit_price": 123,
          "revenue_growth_rate": 123,
          "revenue_by_source": {
            "video": 123,
            "live": 123,
            "mall": 123,
            "search": 123
          },
          "products_sold_count": 123,
          "creators_count": 123,
          "videos_count": 123,
          "livestreams_count": 123
        },
        "period": {
          "start": "2023-12-25",
          "end": "2023-12-25",
          "granularity": "day",
          "adjusted": true
        },
        "currency": "<string>",
        "meta": {
          "refreshed_at": "2023-11-07T05:31:56Z",
          "completeness": 0.5,
          "missing_fields": [
            "<string>"
          ]
        }
      },
      "meta": {
        "refreshed_at": "2023-11-07T05:31:56Z",
        "completeness": 0.5,
        "missing_fields": [
          "<string>"
        ]
      }
    }
  ],
  "period": {
    "start": "2023-12-25",
    "end": "2023-12-25",
    "granularity": "day",
    "adjusted": true
  },
  "currency": "<string>",
  "credits_charged": 123
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "filters.revenue.gte must be a non-negative number.",
    "param": "filters.revenue.gte",
    "doc_url": "https://unif.dev/docs/platform/errors#parameter_invalid",
    "request_id": "req_01k3m9x7v2q8r4t6y0b1n5d7fa"
  }
}

{
  "error": {
    "type": "billing_error",
    "code": "insufficient_credits",
    "message": "This request costs 25 credits and 4 remain in the current period.",
    "doc_url": "https://unif.dev/docs/platform/credits",
    "request_id": "req_01k3m9x7v2q8r4t6y0b1n5d7fa"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "request_id": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Send your workspace API key as a bearer token:

Authorization: Bearer unif_sk_live_...

Keys are scoped to a single workspace. See Authentication.

Headers

Idempotency-Key

string

A unique key, at most 255 characters. Retrying with the same key returns the original response instead of doing the work twice. Keys are retained for 24 hours.

Body

application/json

inputs

object[]

required

Required array length: 1 - 100 elements

Hide child attributes

inputs.type

enum<string>

required

Available options:

shop,

product,

creator,

video,

livestream,

category

inputs.url

string<uri>

A channel URL for the entity.

inputs.handle

string

The channel handle

inputs.external_id

string

The entity's native ID on the channel.

inputs.channel

enum<string>

A sales channel — the commerce surface a request is about. Behind each channel is a cascade of data sources, tried in cost order until one verifies; the roster is published, but which source answered a given row is not carried in the response, so the cascade can be re-tuned without breaking your code.

Available options:

tiktok_shop

Example:

"tiktok_shop"

inputs.market

enum<string>

An ISO 3166-1 alpha-2 country code identifying a channel storefront.

Available options:

US,

GB,

IE,

ES,

FR,

DE,

IT,

ID,

TH,

VN,

MY,

PH,

SG,

JP,

BR,

MX

Example:

"US"

inputs.ref

string

Your own identifier

fields

string[]

Dot-paths to return, for example metrics.revenue. Omit to return the full record. Narrowing the field set lowers the credit cost.

period

object

The window a metric is measured over. Supply either preset, or both start and end. Periods are whole days in the market's local time zone.

Hide child attributes

period.preset

enum<string>

default:last_30d

Available options:

last_7d,

last_30d,

last_90d,

last_180d,

month_to_date,

previous_month

period.start

string<date>

First day

period.end

string<date>

Last day

Examples:

{ "preset": "last_30d" }

{
  "start": "2026-08-01",
  "end": "2026-08-31"
}

currency

string

default:USD

Response

Enrichment results, in the order the inputs were sent.

object

string

Allowed value: "enrich_response"

data

object[]

Hide child attributes

data.ref

string | null

data.status

enum<string>

Available options:

enriched,

not_found,

ambiguous,

unsupported,

partial

data.type

enum<string>

Available options:

shop,

product,

creator,

video,

livestream,

category

data.data

object

The normalized entity, shaped by fields. Null unless status is enriched or partial.

Option 1
Option 2
Option 3
Option 4
Option 5

Hide child attributes

data.data.id

string

Example:

"shp_01k3m9x7v2q8r4t6y0b1n5d7fa"

data.data.object

string

Allowed value: "shop"

data.data.channel

enum<string>

Available options:

tiktok_shop

Example:

"tiktok_shop"

data.data.market

enum<string>

An ISO 3166-1 alpha-2 country code identifying a channel storefront.

Available options:

US,

GB,

IE,

ES,

FR,

DE,

IT,

ID,

TH,

VN,

MY,

PH,

SG,

JP,

BR,

MX

Example:

"US"

data.data.name

string

Example:

"GlowLab"

data.data.handle

string

Example:

"glowlab"

data.data.url

string<uri>

data.data.logo_url

string<uri>

data.data.seller_type

enum<string>

Normalized seller classification.

Available options:

brand,

reseller,

cross_border,

local,

unknown

data.data.categories

object[]

Hide child attributes

data.data.categories.id

string

Example:

"cat_beauty_personal_care"

data.data.categories.name

string

Example:

"Beauty & Personal Care"

data.data.categories.path

string[]

Names from the root down to this category.

data.data.rating

number | null

Required range: 0 <= x <= 5

data.data.reviews_count

integer | null

data.data.products_count

integer | null

data.data.opened_at

string<date> | null

data.data.metrics

object

Shop performance over the requested period, in the requested currency.

Hide child attributes

data.data.metrics.revenue

number

Gross merchandise value attributed to the shop.

data.data.metrics.units_sold

integer

data.data.metrics.avg_unit_price

number

data.data.metrics.revenue_growth_rate

number

Change in revenue against the immediately preceding period of equal length, as a ratio. 0.25 is +25%.

data.data.metrics.revenue_by_source

object

Share of revenue by selling surface. Values sum to 1.

Hide child attributes

data.data.metrics.revenue_by_source.video

number

data.data.metrics.revenue_by_source.live

number

data.data.metrics.revenue_by_source.mall

number

data.data.metrics.revenue_by_source.search

number

data.data.metrics.products_sold_count

integer

Distinct products with at least one sale.

data.data.metrics.creators_count

integer

Distinct creators who drove attributed sales.

data.data.metrics.videos_count

integer

data.data.metrics.livestreams_count

integer

data.data.period

object

The concrete window a request was measured over, after any preset was expanded and any channel-specific snapping was applied. Always read this rather than assuming you got back exactly the dates you asked for.

Hide child attributes

data.data.period.start

string<date>

required

data.data.period.end

string<date>

required

data.data.period.granularity

enum<string>

The smallest bucket the channel reports for this market.

Available options:

day,

week,

month

data.data.period.adjusted

boolean

True when the requested dates were snapped to the nearest boundary the channel supports. See Periods and currency.

data.data.currency

string

data.data.meta

object

How current and how complete this record is.

Hide child attributes

data.data.meta.refreshed_at

string<date-time>

When Unif last refreshed this record.

data.data.meta.completeness

number

Share of the requested fields that were populated.

Required range: 0 <= x <= 1

data.data.meta.missing_fields

string[]

Fields that are not covered for this channel and market.

data.meta

object

How current and how complete this record is.

Hide child attributes

data.meta.refreshed_at

string<date-time>

When Unif last refreshed this record.

data.meta.completeness

number

Share of the requested fields that were populated.

Required range: 0 <= x <= 1

data.meta.missing_fields

string[]

Fields that are not covered for this channel and market.

period

object

Hide child attributes

period.start

string<date>

required

period.end

string<date>

required

period.granularity

enum<string>

The smallest bucket the channel reports for this market.

Available options:

day,

week,

month

period.adjusted

boolean

True when the requested dates were snapped to the nearest boundary the channel supports. See Periods and currency.

currency

string

credits_charged

integer

Overview

Meta

Shops

Products

Creators

Videos

Livestreams

Categories

Resolution

Jobs

Lists

Trackers

Webhooks

Usage

Enrich known entities

Authorizations

Headers

Body

Response