The Swordfish Knowledge Base

What Is the Swordfish API?

The Swordfish "Search by Data" API lets you use existing data points you have for a person—like their name, email, phone, or social profile—and retrieve verified contact details programmatically. It's perfect for teams who want to integrate Swordfish data into their own tools and workflows.

Who Can Use the API?

API access is available on:

• Team & Scale Plan and higher
• Enterprise Plan

API access requires approval. Contact support@swordfish.ai with your use case to get started.

Getting Your API Key

1. Log into Swordfish
2. Go to Settings → API Key
3. Your unique API key is displayed (format: live-xxxxxxxxxxxx)
4. Click to copy it, or click Renew API Key to generate a new one

Keep your API key secret — Never share it publicly or commit it to public code repositories.

API Endpoint

All person searches use a single endpoint:

https://api.swordfish.ai/searchPerson

Requests must be sent as POST with a JSON body, over HTTPS (SSL required).

Request Headers

Include these headers with every request:

You can also pass your API key as a URL parameter:

https://api.swordfish.ai/searchPerson?apikey=live-xxxxxxxxxxxx

Supported Search Combinations

The API requires one of these base combinations to return results. Requests that don't match a supported combination return an error or no results.

Supported combinations:

• social_profile — LinkedIn, Facebook, or Twitter/X URL
• first_name + last_name + website (company domain)
• first_name + last_name + company + website
• first_name + last_name + company + title
• first_name + last_name + email
• first_name + last_name + phone
• first_name + last_name + street + zipcode (US addresses only)

Standalone search fields (can be used alone with no additional data):

• social_profile
• email
• phone

Important: Only one value can be sent for each data point. You cannot send multiple emails or multiple phones in a single request.

The must_have Key

The must_have key helps ensure you only pay for the data you need. It verifies that any valid response includes the data you specify—exactly like the "must have" toggles in the Extension, Reverse Lookup, and File Enrichment.

Set must_have to a number between 1 and 7:

Note: If you use summary, the must_have key is ignored.

Example Request

A search by full name requiring any email:

{
  "must_have": 1,
  "fullname": "Bruce Wayne"
}

A search by email only:

{
  "email": "bruce@wayne.com"
}

A search by name and company:

{
  "must_have": 5,
  "first_name": "Bruce",
  "last_name": "Wayne",
  "company": "Wayne Enterprises"
}

Responses

The API returns one of two responses:

No match — You'll see "no match found" in the JSON response. This means that based on the data sent and the must_have value, we couldn't match a single person.

Match — You'll see the contact details in the JSON response (name, emails, phones, social profiles).

Error Handling

General Errors

Data-Related Errors

Limits

• Concurrent requests: Each API key is limited to 5 active requests at the same time
• Fair use: API usage counts toward your weekly fair use threshold (unlimited plans) or credits (legacy plans)

If you hit the limit, contact support@swordfish.ai to request a fair use increase.

Additional Endpoints

The API also includes:

• Get credits balance — Returns the number of credits remaining on your account
• Get history of requests — Retrieve your past API requests by parameter

See the full API documentation for details on these endpoints, including request and response formats.

Security & Authorization

• All requests must be encrypted using SSL (HTTPS)
• Your API key authenticates each request
• Store your key securely (environment variables, not hardcoded)
• Rotate your key periodically via Settings → API Key → Renew API Key

Full Documentation

For complete API documentation including all endpoints, request/response examples, and code samples, visit:

Swordfish API Documentation

You can also click Run in Postman on that page to test requests directly.

Getting Started

1. Make sure you're on Team & Scale or higher
2. Email support@swordfish.ai to request API access
3. Once approved, go to Settings → API Key to get your key
4. Review the full documentation
5. Start building!

Questions? Email support@swordfish.ai with your use case and we'll help.