Flag

Report incorrect data and hard bounces for credit recovery

List My Flags

GET

https://api.tomba.io/v1

/flag

X-Tomba-Key (header)

+X-Tomba-Secret (header)

Returns a paginated list of data flags submitted by the authenticated user, including their current status (pending, confirmed, rejected) and any credits refunded.

List My Flags › query Parameters

page

integer · min: 1

Page number for pagination

Default: 1

limit

integer · min: 1 · max: 100

Number of results per page

Default: 10

List My Flags › Responses

Paginated list of flags

FlagListResponse

FlagItem[]

Array of flag reports

PaginationMeta

Flag Incorrect Data

POST

https://api.tomba.io/v1

/flag

X-Tomba-Key (header)

+X-Tomba-Secret (header)

Report incorrect data such as hard bounces, invalid emails, wrong organization info, phone numbers, author URLs, or websites. Hard bounces are on us — report it and we'll make it right. Once confirmed, credits are refunded automatically.

Flag Incorrect Data › Request Body

FlagCreateRequest

flag_type

string · enum · required

Type of data being flagged

Enum values:

organization

phone

author_url

website

value

string · minLength: 2 · maxLength: 255 · required

The flagged item (email address, domain, phone number, URL)

reason

string · enum · required

Reason for flagging. Valid reasons depend on flag_type: email(hard_bounce,invalid_email,wrong_person,outdated,other), organization(wrong_company,outdated,other), phone(wrong_phone,outdated,other), author_url(broken_url,wrong_person,outdated,other), website(broken_url,wrong_company,outdated,other)

Enum values:

hard_bounce

invalid_email

wrong_person

outdated

wrong_company

wrong_phone

broken_url

other

comment

string · maxLength: 1000

Optional additional details about the issue

Flag Incorrect Data › Responses

Flag created successfully

FlagResponse

FlagItem

POST/flag

curl https://api.tomba.io/v1/flag \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-Tomba-Key: <api-key>' \
  --header 'X-Tomba-Secret: <api-key>' \
  --data '{
  "flag_type": "email",
  "value": "bounced@example.com",
  "reason": "hard_bounce",
  "comment": "Email hard bounced on 2026-08-25"
}'

Example Request Body

{
  "flag_type": "email",
  "value": "bounced@example.com",
  "reason": "hard_bounce",
  "comment": "Email hard bounced on 2026-08-25"
}

json

application/json

Example Responses

{
  "data": {
    "id": 0,
    "flag_type": "email",
    "value": "value",
    "reason": "reason",
    "comment": "comment",
    "status": "pending",
    "credits_refunded": 0,
    "resolved_at": "2024-08-25T15:00:00Z",
    "created_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Keys MCP Server

List My Flags

GET

https://api.tomba.io/v1

/flag

X-Tomba-Key (header)

+X-Tomba-Secret (header)

Returns a paginated list of data flags submitted by the authenticated user, including their current status (pending, confirmed, rejected) and any credits refunded.

List My Flags › query Parameters

page

integer · min: 1

Page number for pagination

Default: 1

limit

integer · min: 1 · max: 100

Number of results per page

Default: 10

List My Flags › Responses

Paginated list of flags

FlagListResponse

FlagItem[]

Array of flag reports

PaginationMeta

Flag Incorrect Data

POST

https://api.tomba.io/v1

/flag

X-Tomba-Key (header)

+X-Tomba-Secret (header)

Flag Incorrect Data › Request Body

FlagCreateRequest

flag_type

string · enum · required

Type of data being flagged

Enum values:

organization

phone

author_url

website

value

string · minLength: 2 · maxLength: 255 · required

The flagged item (email address, domain, phone number, URL)

reason

string · enum · required

Enum values:

hard_bounce

invalid_email

wrong_person

outdated

wrong_company

wrong_phone

broken_url

other

comment

string · maxLength: 1000

Optional additional details about the issue

Flag Incorrect Data › Responses

Flag created successfully

FlagResponse

FlagItem