Flag

Report incorrect data and hard bounces

List My Flags

GET

https://api.tomba.io/v1

/flag

X-Tomba-Key (header)

+X-Tomba-Secret (header)

Returns the reports you submitted, with their review status and any credits returned. Only your own reports are listed, not your workspace's.

GET /flag is limited to 10 requests per minute per IP address; failed requests don't count. It also accepts an OAuth 2.0 access token, with any scope.

List My Flags › query Parameters

page

integer · min: 1

Page number, starting at 1.

Default: 1

limit

integer · min: 1

Reports per page.

Default: 10

direction

string · enum

Sort order by report ID. desc returns the newest reports first.

Enum values:

desc

asc

Default: desc

List My Flags › Responses

A page of your reports.

FlagListResponse

FlagItem[] · required

Your reports, one page at a time.

PaginationMeta · required

GET/flag

curl https://api.tomba.io/v1/flag \
  --header 'X-Tomba-Key: <api-key>' \
  --header 'X-Tomba-Secret: <api-key>'

Example Responses

{
  "data": [
    {
      "id": 102,
      "flag_type": "organization",
      "value": "stripe.com",
      "reason": "wrong_company",
      "comment": "The company name is out of date.",
      "status": "pending",
      "credits_refunded": 0,
      "created_at": "2026-09-26T14:30:00Z"
    },
    {
      "id": 101,
      "flag_type": "email",
      "value": "jane.doe@stripe.com",
      "reason": "hard_bounce",
      "comment": "550 5.1.1 The email account that you tried to reach does not exist.",
      "status": "confirmed",
      "credits_refunded": 1,
      "resolved_at": "2026-09-26T09:12:00Z",
      "created_at": "2026-09-25T10:00:00Z"
    }
  ],
  "meta": {
    "total": 2,
    "pageSize": 10,
    "current": 1,
    "total_pages": 1
  }
}

json

application/json

Flag Incorrect Data

POST

https://api.tomba.io/v1

/flag

X-Tomba-Key (header)

+X-Tomba-Secret (header)

Reports incorrect data: an email address that bounced or is wrong, or a wrong organization, phone number, author URL, or website. reason must be one of the reasons listed for the flag_type.

Tomba reviews each report by hand. A new report has the status pending; follow it with GET /flag. When Tomba confirms an email report with the reason hard_bounce, it returns one search credit to the usage window that's current at that moment, and the report's credits_refunded becomes 1. Verification credits aren't returned, and other types and reasons don't return credits. See Refunds for incorrect data.

Reporting an item again with the same flag_type while your earlier report is still pending fails with 409. POST /flag is limited to 10 requests per minute per IP address; failed requests don't count. It also accepts an OAuth 2.0 access token, with any scope.

Flag Incorrect Data › Request Body

FlagCreateRequest

flag_type

string · enum · required

What you're reporting.

Enum values:

organization

phone

author_url

website

value

string · minLength: 2 · maxLength: 255 · required

The item you're reporting, such as the email address, domain, phone number, or URL.

reason

string · enum · required

Why the data is wrong. Each flag_type accepts its own reasons, and any other combination fails with 422:

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

Only an email report with hard_bounce can return a credit, once Tomba confirms it.

Enum values:

hard_bounce

invalid_email

wrong_person

outdated

wrong_company

wrong_phone

broken_url

other

comment

string · maxLength: 1000

Details that help Tomba review the report, such as the bounce message your mail server received.

Flag Incorrect Data › Responses

Report created, pending review.

FlagResponse

FlagItem · required

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": "jane.doe@stripe.com",
  "reason": "hard_bounce",
  "comment": "550 5.1.1 The email account that you tried to reach does not exist."
}'

Example Request Body

{
  "flag_type": "email",
  "value": "jane.doe@stripe.com",
  "reason": "hard_bounce",
  "comment": "550 5.1.1 The email account that you tried to reach does not exist."
}

json

application/json

Example Responses

{
  "data": {
    "id": 101,
    "flag_type": "email",
    "value": "jane.doe@stripe.com",
    "reason": "hard_bounce",
    "comment": "550 5.1.1 The email account that you tried to reach does not exist.",
    "status": "pending",
    "credits_refunded": 0,
    "created_at": "2026-09-25T10: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 the reports you submitted, with their review status and any credits returned. Only your own reports are listed, not your workspace's.

GET /flag is limited to 10 requests per minute per IP address; failed requests don't count. It also accepts an OAuth 2.0 access token, with any scope.

List My Flags › query Parameters

page

integer · min: 1

Page number, starting at 1.

Default: 1

limit

integer · min: 1

Reports per page.

Default: 10

direction

string · enum

Sort order by report ID. desc returns the newest reports first.

Enum values:

desc

asc

Default: desc

List My Flags › Responses

A page of your reports.

FlagListResponse

FlagItem[] · required

Your reports, one page at a time.

PaginationMeta · required

Flag Incorrect Data

POST

https://api.tomba.io/v1

/flag

X-Tomba-Key (header)

+X-Tomba-Secret (header)

Reports incorrect data: an email address that bounced or is wrong, or a wrong organization, phone number, author URL, or website. reason must be one of the reasons listed for the flag_type.

Flag Incorrect Data › Request Body

FlagCreateRequest

flag_type

string · enum · required

What you're reporting.

Enum values:

organization

phone

author_url

website

value

string · minLength: 2 · maxLength: 255 · required

The item you're reporting, such as the email address, domain, phone number, or URL.

reason

string · enum · required

Why the data is wrong. Each flag_type accepts its own reasons, and any other combination fails with 422:

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

Only an email report with hard_bounce can return a credit, once Tomba confirms it.

Enum values:

hard_bounce

invalid_email

wrong_person

outdated

wrong_company

wrong_phone

broken_url

other

comment

string · maxLength: 1000

Details that help Tomba review the report, such as the bounce message your mail server received.

Flag Incorrect Data › Responses

Report created, pending review.

FlagResponse

FlagItem · required