The Swordfish \"Search by data\" API allows you to use existing data points you have for a person and retrieve relevant contact details.
\nThe API requires one of the following base combinations to return results. Requests that do not match a supported combination will return an error or no results.
\nsocial_profile — LinkedIn, Facebook, or Twitter/X URL
\nfirst_name + last_name + website — company domain
\nfirst_name + last_name + company + website
\nfirst_name + last_name + company + title
\nfirst_name + last_name + email
\nfirst_name + last_name + phone
\nfirst_name + last_name + street + zipcode — US addresses only
\nThe following fields can be used as standalone search fields without any additional data:
\nsocial_profile
\nphone
\nImportant:
\nOnly one value can be sent for each data point. For example, multiple emails or multiple phones are not accepted in a single request at this time.
\nThe data points, or as we refer to it as the base of the search, should be sent in a JSON object in the body of the API request.
\nThe Swordfish API endpoint is https://api.swordfish.ai/searchPerson and should include the following keys and values in the header:
\nThe Swordfish API a json body which includes the different data fields to search by and a \"must_have\" key to help you make sure you pay only for the data you need. It works exactly like the \"must_have\" key on the Swordfish Extension, Deep Search and File Upload, and verifies that any valid response you receive will include the data you specify.
\nThe must_have key should be part of the JSON object in the body of the request. The valid values for this key is a number between 1 and 7 indicating what the 'must_have' combination is.
\n'must have' combination legend:
\nExample of a body including 'must_have' for 'Any email':
\n{\n \"must_have\":1,\n \"fullname\":\"Bruce Wayne\"\n}\n\nNote: if is use \"summary\" then must_have will be ignored
\nThe API can return one of two possible responses:
\nNo match - You will see the \"no match found\" in the JSON object response. This means that based on the data sent and the 'musthave' value, we could not match a single person to return.
\nMatch - You will see the contact details in the JSON object responses.
\nGENERAL ERRORS
\nBelow is a list of general errors and possible ways to tackle these in your code or data.
\nDATA RELATED ERRORS
\nBelow is a list of errors related specifically to the data in the request and possible ways to tackle these in your code or data.
\nAll requests must be encrypted using SSL (https) when sent to Swordfish servers.
\nYou will need to get access to your API key from your account. Once the key has been issued to you you will be able to view it on your Settings tab.
\nThe API key is usually part of the header but can also be sent as a parameter in the URL as in the example below:
https://api.swordfish.ai/searchPerson?apikey=live-xxxxxxxxxxxx
The Swordfish API limits each key to 5 active requests at the same time. This is the number of requests that the system can process simultaneously by a specific key.
\nThe Swordfish API has a dedicated request to return you the number of credits you have remaining on your account. See the \"Get credits balance\" section below.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Supported Search Combinations","slug":"supported-search-combinations"},{"content":"Requests","slug":"requests"},{"content":"Responses","slug":"responses"},{"content":"Error Handling","slug":"error-handling"},{"content":"Security and Authorization","slug":"security-and-authorization"},{"content":"Limits","slug":"limits"},{"content":"Credit Balance","slug":"credit-balance"}],"owner":"13503793","collectionId":"2556a0fa-74c5-467b-81fa-5c7aac7d461e","publishedId":"TVewZQLj","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"publishDate":"2024-09-25T10:46:53.000Z"},"item":[{"name":"Search by data - Multiple fields","id":"74775252-0eac-48ec-afc6-c90261fdc0d7","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"must_have\":3,\r\n \"fullname\":\"\",\r\n \"social_profile\":\"https://www.linkedin.com/in/bruce-wayne-570388131/\",\r\n \"email\":\"bruce@wayneenterprises.com\"\r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.swordfish.ai/searchPerson","description":"The Swordfish \"Search by data\" API allows you to use existing data points you have for a person and retrieve relevant contact details.
\nThe API requires one of the following base combinations to return results. Requests that do not match a supported combination will return an error or no results.
\nsocial_profile — LinkedIn, Facebook, or Twitter/X URL
\nfirst_name + last_name + website — company domain
\nfirst_name + last_name + company + website
\nfirst_name + last_name + company + title
\nfirst_name + last_name + email
\nfirst_name + last_name + phone
\nfirst_name + last_name + street + zipcode — US addresses only
\nThe following fields can be used as standalone search fields without any additional data:
\nsocial_profile
\nphone
\nImportant:
\nOnly one value can be sent for each data point. For example, multiple emails or multiple phones are not accepted in a single request at this time.
\nThe data points, or as we refer to it as the base of the search, should be sent in a JSON object in the body of the API request.
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"apikey"},{"key":"value","value":"The Swordfish \"Search by data\" API allows you to use existing data points you have for a person and retrieve relevant contact details.
\nThe API requires one of the following base combinations to return results. Requests that do not match a supported combination will return an error or no results.
\nsocial_profile — LinkedIn, Facebook, or Twitter/X URL
\nfirst_name + last_name + website — company domain
\nfirst_name + last_name + company + website
\nfirst_name + last_name + company + title
\nfirst_name + last_name + email
\nfirst_name + last_name + phone
\nfirst_name + last_name + street + zipcode — US addresses only
\nThe following fields can be used as standalone search fields without any additional data:
\nsocial_profile
\nphone
\nImportant Rule: Only one value can be sent for each data point. For example, multiple emails or multiple phones are not accepted in a single request at this time.
\nTo convert this into a summary call, you only need to add the \"summary\" parameter in the request header with a value of true or 1. This will return a summarized preview of available contact information, rather than the complete dataset.
{ \"apikey\": \"live-xxxxxxxxxxxx\", \"content-type\": \"application/json\", \"summary\": \"true\" }
Summary calls provide a quick overview but may show fewer data points. More information might be available after you proceed with the full request.
\nSummary calls provide a quick overview of the data points that may be available. However, it's important to understand that the summary only indicates that it is possible for us to find this contact information with our data partners. It does not guarantee that all the shown data will be found after using your credits.
\nIf the \"summary\" parameter is used, the must_have key will be ignored, meaning specific contact details won’t be guaranteed in the response.
When the summary parameter is used, the response will include a summary of available contact information. The detailed data will be excluded, and instead, a list of available data types will be returned, like so:
{\n \"summary\": [\n \"mobile_phone\",\n \"work_phone\",\n \"email\",\n \"linkedin_url\",\n \"facebook_url\",\n \"twitter_url\"\n ]\n}\n\nIt’s important to note that while the summary indicates the data types available (e.g., mobile phone, email, social profiles), nothing is guaranteed. You may receive only part of the available data in a detailed response (for example, just the mobile phone number), and there is always a possibility that further data is not available or cannot be retrieved.
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"apikey"},{"key":"value","value":"The Swordfish \"Search by data\" API allows you to use existing data points you have for a person and retrieve relevant contact details.
\nThe API accepts the following data points:
\nsocial_profile — LinkedIn, Facebook, or Twitter/X URL
\nfirst_name + last_name + website — company domain
\nfirst_name + last_name + company + website
\nfirst_name + last_name + company + title
\nfirst_name + last_name + email
\nfirst_name + last_name + phone
\nfirst_name + last_name + street + zipcode — US addresses only
\nYou can only send one value for each data point. Multiple values such as, multiple emails or multiple phones, are not valid at the moment.
\nMinimum required data for a valid request, i.e. these fields can be sent without any other data:
\nSocial Profile
\nPhone
\nImportant:
\nOnly one value can be sent for each data point. For example, multiple emails or multiple phones are not accepted in a single request at this time.
\nThe data points, or as we refer to it as the base of the search, should be sent in a JSON object in the body of the API request.
\n","urlObject":{"protocol":"https","path":["searchPerson"],"host":["api","swordfish","ai"],"query":[],"variable":[]}},"response":[{"id":"fb31e2d5-944f-417b-b351-28b436526267","name":"Search by data - Multiple fileds","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"must_have\":3,\r\n \"fullname\": \"\",\r\n \"first_name\": \"Bruce\",\r\n \"middle_name\": \"\",\r\n \"last_name\": \"Wayne\",\r\n \"social_profile\":\"https://www.linkedin.com/in/bruce-wayne-570388131/\",\r\n \"email\": \"bruce@wayneenterprises.com\",\r\n \"phone\": \"\",\r\n \"city\": \"\",\r\n \"state\": \"\",\r\n \"country\": \"\",\r\n \"zipcode\": \"\"\r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.swordfish.ai/searchPerson"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"},{"key":"Date","value":"Mon, 07 Dec 2020 08:53:38 GMT"}],"cookie":[],"responseTime":null,"body":"{\n \"company\": \"Wayne Enterprises\",\n \"emails\": [\n \"brucelecomte@gmail.com\"\n ],\n \"name\": \"Bruce Wayne\",\n \"phones\": {\n \"mobile\": [\n \"+33 6 27 62 18 49\"\n ],\n \"work\": [\n \"+33 1 49 74 01 99\",\n \"+33 1 72 50 42 70\"\n ]\n },\n \"social_profiles\": {\n \"linkedin\": \"https://www.linkedin.com/in/bruce-wayne-570388131\"\n },\n \"title\": \"CEO\"\n}"}],"_postman_id":"817a9fe6-db99-4811-97dd-a00baa9f2435"},{"name":"Search by data - Name & Company & Title","id":"877a5423-03a2-4f64-9f60-72ba64300175","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"apikey"},{"key":"value","value":"This example shows what data is usually available off social platforms and can be used to retrieve contact information when social profile does not return data.
\nTitle is also a valid field to be used in any search. We strongly recommend that it is not used without a relevant company name that the searched individual worked at. This can affect the accuracy of the response.
\n","urlObject":{"protocol":"https","path":["searchPerson"],"host":["api","swordfish","ai"],"query":[],"variable":[]}},"response":[],"_postman_id":"877a5423-03a2-4f64-9f60-72ba64300175"},{"name":"Name & Company & Title","id":"04a948c5-2cee-44a1-91e4-30a9bd911df2","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"must_have\": 1,\r\n \"first_name\": \"William\",\r\n \"last_name\": \"Gates\",\r\n \"middle_name\": \"Henry\",\r\n \"company\": \"Microsoft\"\r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.swordfish.ai/searchPerson","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"apikey"},{"key":"value","value":"The social_profile key accepts one of the following values: URL, Username or User ID. \nIt is critical to have the right structure for each of the formats. See examples below:
\nURL - https://www.https://www.linkedin.com/in/batman
\nUsername - batman@linkedin \n(Linkedin users do not have usernames like Facebook users)
\nUserid - 541390116@linkedin
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"apikey"},{"key":"value","value":"API search using only an email address. The example shows a query using only a single email. If you would like to send multiple emails for the same person search, you should use \"Emails\" and list the emails as the value.
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"apikey"},{"key":"value","value":"Returns a paginated history of API requests made by your account. Use the parameters below to filter by date range, status, or specific request ID.
\n","urlObject":{"protocol":"https","path":["getHistory"],"host":["api","swordfish","ai"],"query":[{"description":{"content":"unix_timestamp of start period datetime (not mandatory)
\n","type":"text/plain"},"key":"dt_from","value":"1735682400"},{"description":{"content":"unix_timestamp of end period datetime (not mandatory)
\n","type":"text/plain"},"key":"dt_to","value":"1738360800"},{"description":{"content":"1 - with result, 0 - without result (not mandatory)
\n","type":"text/plain"},"key":"status","value":"1"},{"description":{"content":"id of request (not mandatory)
\n","type":"text/plain"},"key":"id","value":"12345"},{"description":{"content":"number of page (total per page - 100 rows)
\n","type":"text/plain"},"key":"page","value":"3"}],"variable":[]}},"response":[],"_postman_id":"7c0b763b-d3de-4c77-b802-e37b65c9ab81"}],"auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"apikey"},{"key":"value","value":"