> ## Documentation Index > Fetch the complete documentation index at: https://docs.seamless.ai/llms.txt > Use this file to discover all available pages before exploring further. # Poll Contact Research > Get the results/status of a contact research request ## OpenAPI ````yaml https://gist.githubusercontent.com/JustinAlia/6ff38a671f5f79895444b77c57f3afff/raw/v2-openapi.json get /contacts/research/poll openapi: 3.0.0 info: title: Seamless API description: >- [Privacy Policy](https://seamless.ai/policies/privacy-policy) In order to dramatically improve our offerings to customers, Seamless will be introducing a Public API which can be used to search Companies & Contacts, Enrich Lists, and offer integrations as an Endpoint for our customers. The API is build using [RESTful](https://en.wikipedia.org/wiki/REST) principles and is secured using OAuth 2.0 with the implicit grant flow. # Authentication ## API Key ### 1. **Register Your Application** To use the Seamless API, you need to register your application to obtain an API key. To create a new API key, go to [Seamless.AI | Settings](https://login.seamless.ai/settings/public-api) > API Key and click the *Create New Connection* button. Note: The Public API Connections menu will only appear if your account has access to the Public API. ### 2. **Use the Access Token** For all authenticated API requests, include the API key in the header: ``` Token: API_KEY ``` ## OAuth 2.0 ### 1. **Register Your Application** Before integrating, you have to setup your client credentials. To create a new API client, go to [Seamless.AI | Settings](https://login.seamless.ai/settings/public-api) > OAuth Connections, and click the *Create New Connection* button. Note: The Public API Connections menu will only appear if your account has access to the Public API. - `client_id` - `client_secret` - `redirect_uri` You’ll use these to authenticate and obtain tokens. --- ### 2. **Obtain Authorization Code** Redirect the user to Seamless.AI's OAuth authorization endpoint: ``` GET https://login.seamless.ai/oauth/authorize ``` ### Query Parameters: | Name | Description | | --- | --- | | `client_id` | Your client ID | | `redirect_uri` | The URL users are redirected to | | `state` | (Optional) CSRF protection string | **Example URL**: ``` GET https://login.seamless.ai/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https://yourapp.com/callback ``` Once the user authenticates, they will be redirected to your `redirect_uri` with a `code` parameter. If your `redirect_uri` contains any query parameters (such as `?foo=bar`), you must URL encode your `redirect_uri` for this step. --- ### 3. **Exchange Code for Access Token** ``` POST https://api.seamless.ai/api/client/v2/oauth/accessToken ``` ### Request Body (JSON): ```json { "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET", "redirect_uri": "https://yourapp.com/callback", "grant_type": "authorization_code", "code": "AUTHORIZATION_CODE_FROM_STEP_2" } ``` ### Response: ```json { "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "refresh_token": "REFRESH_TOKEN", "expires_in": 10800, "expires_at": "2026-06-25T12:00:00.000Z", "refresh_token_expires_in": 604800, "refresh_token_expires_at": "2026-07-02T12:00:00.000Z" } ``` Access tokens expire after **180 minutes** by default. Integrations must use the `refresh_token` grant before expiry to obtain a new token pair. Existing long-lived tokens issued before this change remain valid until their original expiry. --- ### 4. **Use the Access Token** For all authenticated API requests, include the token in the header: ``` Authorization: Bearer ACCESS_TOKEN ``` --- ### 5. **Refreshing the Token** To refresh the access token: ``` POST https://api.seamless.ai/api/client/v2/oauth/accessToken ``` ### Request Body: ```json { "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET", "redirect_uri": "https://yourapp.com/callback", "grant_type": "refresh_token", "refresh_token": "YOUR_REFRESH_TOKEN" } ``` ### Response: ```json { "token_type": "Bearer", "access_token": "NEW_ACCESS_TOKEN", "refresh_token": "NEW_REFRESH_TOKEN", "expires_in": 10800, "expires_at": "2026-06-25T12:00:00.000Z", "refresh_token_expires_in": 604800, "refresh_token_expires_at": "2026-07-02T12:00:00.000Z" } ``` Each refresh rotates both the access and refresh tokens. Store the new `refresh_token` from every response. # Rate Limiting Rate limits are enforced at the **organization** level. All API usage for your Seamless organization counts against the same quota for each endpoint—limits are not applied separately per API key or per user. The default limit is **60 requests per minute** per endpoint. If you exceed the limit, the API responds with **429 Too Many Requests** and a JSON error body. Some endpoints may use different limits (for example, OAuth routes). Your organization may also have custom limits. The `X-RateLimit-Limit` header on each response always reflects the maximum number of requests allowed for that endpoint in the current rate limit window. Rate limit and remaining credits information will be returned in the response header of each request. The parameters are: | Name | Example | Description | | --- | --- | --- | | `X-RateLimit-Limit` | 60 | The maximum number of requests you're permitted to make in the current rate limit window for this endpoint. | | `X-RateLimit-Remaining` | 42 | The number of requests remaining in the current rate limit window. | | `X-RateLimit-Reset` | 1745587198 | The time at which the current rate limit window resets in epoch seconds. | | `X-PublicAPI-Credits` | 1000 | The number of credits remaining that can be used in requests. | version: 1.0.0 x-logo: url: https://s3.amazonaws.com/seamless.ai-public/logos/logo-full-dark.svg altText: Seamless logo href: https://login.seamless.ai termsOfService: https://seamless.ai/policies/terms-of-use servers: - url: https://api.seamless.ai/api/client/v2 description: Seamless API security: - OAuth2: [] - ApiKeyAuth: [] tags: - name: OAuth description: >- Exchange client credentials for an access token and inspect the authenticated caller. - name: Contact Search description: >- Search the Seamless.AI contact database. Searching does not consume credits; researching a result does. - name: Company Search description: >- Search the Seamless.AI company database. Searching does not consume credits; researching a result does. - name: Contact Research description: >- Resolve a contact's emails and phone numbers. Research is asynchronous: submit a request, then poll for results or receive them by webhook. - name: Company Research description: >- Resolve company firmographics and contact details. Research is asynchronous: submit a request, then poll for results or receive them by webhook. - name: Org Contacts description: >- Read and update the contacts already saved to your organization. These are the records research writes to, and the IDs other endpoints expect. - name: Org Companies description: Read and update the companies already saved to your organization. - name: Campaigns description: >- Create and run multi-step outbound campaigns, manage their steps, and enroll or remove contacts. - name: Emails description: Compose, preview, send, and track emails, individually or in bulk. - name: Tasks description: Read and act on the tasks a campaign generates for its assigned user. - name: Lists description: Group saved contacts and companies into named lists. - name: Templates description: Reusable email templates available to campaigns and one-off sends. - name: Saved Searches description: Persist search filters so a search can be re-run or shared later. - name: Calls description: >- Log call outcomes against saved contacts, and read the disposition and sentiment vocabularies. - name: Activity description: A chronological feed of engagement activity across your organization. - name: Credits description: Remaining research credits for the authenticated organization. - name: Features description: Feature access flags for the authenticated organization. - name: Reference description: >- Static lookup data — locations, statuses, and other vocabularies other endpoints accept. paths: /contacts/research/poll: get: tags: - Contact Research summary: Poll Contact Research description: Get the results/status of a contact research request operationId: pollContactsResearchResults parameters: - name: requestIds required: true in: query description: >- Comma-separated list of request IDs returned from the /contacts/research endpoint. example: 6Ei5iKuSHzJXvqjVPWiZ_,7Fj6jLvTIAKYwrkWQXjA_ schema: type: array minItems: 1 maxItems: 500 items: type: string responses: '200': description: Poll Results content: application/json: schema: type: object properties: success: type: boolean description: >- Indicates whether the poll request was processed successfully. example: true data: type: array description: Array of research result objects, one per requested ID. items: type: object properties: requestId: type: string description: The research request ID that was polled. example: 6Ei5iKuSHzJXvqjVPWiZ_ searchResultId: type: string description: >- The search result ID associated with this research request, if applicable. example: 11ad7a1c-9a63-30e0-a1de-cd9a766805ca status: type: string description: >- Current status of the research request. Common values include `queued`, `researching`, `done`, `error`, `missing`, `duplicate`, `not found`, `contact-already-researched`, and `No license or credits available`. Additional values may be returned over time. example: done message: type: string description: >- Additional status message, typically populated when the status is error or missing. example: '' contact: type: object description: >- Full contact record returned by the Seamless.AI research engine. Any field may be `null` when the underlying record lacks that attribute — search and research results are sparse, so treat every field below as optional and nullable. properties: contactId: type: string description: Unique identifier for this contact record. example: '699447129' username: type: string description: >- Email address of the Seamless.AI user who researched this contact. example: user@example.com createdAt: type: string format: date-time description: Timestamp when this contact record was created. example: '2026-01-15T10:30:00.000Z' updatedAt: type: string format: date-time description: >- Timestamp when this contact record was last updated. example: '2026-01-15T10:30:00.000Z' firstName: type: string nullable: true description: Contact's first name. example: Jane middleName: type: string nullable: true description: Contact's middle name, if available. example: '' lastName: type: string nullable: true description: Contact's last name. example: Smith fullName: type: string nullable: true description: >- Contact's full display name (first + middle + last). example: Jane Smith name: type: string nullable: true description: Contact's display name. example: Jane Smith nameOriginal: type: string nullable: true description: >- Contact's name as originally sourced, before any normalization. example: Jane Smith email: type: string nullable: true description: Primary email address selected for this contact. example: jsmith@example.com personalEmail: type: string nullable: true description: Personal (non-work) email address, if available. example: '' contactPhone1: type: string nullable: true description: Primary direct phone number for the contact. example: 415.555.0101 contactPhone1TotalAI: type: string nullable: true description: >- Confidence score (percentage) for the primary contact phone number. example: 98% contactPhone1DataType: type: string nullable: true description: >- Type classification of the primary contact phone (e.g., mobile, main). example: mobile contactPhone2: type: string nullable: true description: Secondary direct phone number for the contact. example: 415.555.0102 contactPhone2DataType: type: string nullable: true description: >- Type classification of the secondary contact phone. example: main companyPhone1: type: string nullable: true description: Primary phone number for the contact's company. example: 650.555.0200 companyPhone1TotalAI: type: string nullable: true description: >- Confidence score (percentage) for the primary company phone number. example: 99% companyPhone1DataType: type: string nullable: true description: >- Type classification of the primary company phone. example: company companyPhone2: type: string nullable: true description: >- Secondary phone number for the contact's company. example: 650.555.0201 companyPhone2TotalAI: type: string nullable: true description: >- Confidence score (percentage) for the secondary company phone number. example: 22% companyPhone2DataType: type: string nullable: true description: >- Type classification of the secondary company phone. example: company companyPhone3: type: string nullable: true description: Tertiary phone number for the contact's company. example: 650.555.0202 companyPhone3TotalAI: type: string nullable: true description: >- Confidence score (percentage) for the tertiary company phone number. example: 4% companyPhone3DataType: type: string nullable: true description: >- Type classification of the tertiary company phone. example: company companyName: type: string nullable: true description: >- Current company name of the contact. Same vocabulary as the `companyName` search filter. example: Acme Corp company: deprecated: true type: string nullable: true description: >- Deprecated alias for `companyName`. Prefer `companyName`, which matches the search filter of the same name. example: Acme Corp companyOriginal: type: string nullable: true description: >- Company name as originally sourced, before any normalization. example: Acme Corp companyDescription: type: string nullable: true description: Description or summary of the contact's company. example: >- Acme Corp is a leading provider of innovative business solutions. companyFounded: type: string nullable: true description: Year the company was founded. example: '2004' companyIndustry: type: string nullable: true description: >- Industry classification of the contact's company. example: Computer Software sicCode: type: string nullable: true description: >- Standard Industrial Classification (SIC) code for the contact's company. example: '7389' naicsCode: type: string nullable: true description: >- North American Industry Classification System (NAICS) code for the contact's company. example: '541512' companyStaffCount: type: integer nullable: true description: >- Approximate total number of employees at the company. example: 10001 companySize: type: string nullable: true description: >- Employee count range of the contact's company. Same vocabulary as the `companySize` search filter. example: 10,001+ companyStaffCountRange: deprecated: true type: string nullable: true description: >- Deprecated alias for `companySize`. Prefer `companySize`. The historical label form (`10,001+ employees`) is still returned here; `companySize` uses the search-filter apiValue (`10,001+`). example: 10,001+ employees companyAnnualRevenue: type: string nullable: true description: >- Estimated annual revenue in USD (numeric string). example: '1000000001' companyDomain: type: string nullable: true description: Primary website domain of the company. example: acmecorp.com companyRevenue: type: string nullable: true description: >- Revenue range bucket for the contact's company. Same vocabulary as the `companyRevenue` search filter. example: $1B+ companyRevenueRange: deprecated: true type: string nullable: true description: >- Deprecated alias for `companyRevenue`. Prefer `companyRevenue`, which matches the search filter of the same name. example: $1B+ companyLIProfileUrl: type: string nullable: true description: LinkedIn company page URL. example: https://www.linkedin.com/company/acme-corp companyLinkedInId: type: string nullable: true description: LinkedIn numeric identifier for the company. example: '10667' jobTitle: type: string nullable: true description: >- Contact's current job title. Same vocabulary as the `jobTitle` search filter. example: Finance Director title: deprecated: true type: string nullable: true description: >- Deprecated alias for `jobTitle`. Prefer `jobTitle`, which matches the search filter of the same name. example: Finance Director department: type: string nullable: true description: Department the contact works in. example: Finance seniority: type: string nullable: true description: >- Seniority level of the contact's role (e.g., C-Level, VP, Director, Manager, Senior, Entry Level). example: Director lIProfileUrl: type: string nullable: true description: Contact's LinkedIn public profile URL. example: https://www.linkedin.com/in/janesmith lISalesNavUrl: type: string nullable: true description: Contact's LinkedIn Sales Navigator profile URL. example: https://www.linkedin.com/sales/lead/ACoAAA... lIRecruiterUrl: type: string nullable: true description: Contact's LinkedIn Recruiter profile URL. example: >- https://www.linkedin.com/talent/search/profile/AEMAA... contactLocation: type: object description: Geographic location of the contact. properties: city: type: string nullable: true description: City where the contact is located. example: San Francisco state: type: string nullable: true description: Full state or province name. example: California postCode: type: string nullable: true description: Postal or ZIP code. example: '94107' county: type: string nullable: true description: County name, if available. example: '' country: type: string nullable: true description: Full country name. example: United States stateAbbr: type: string nullable: true description: Two-letter state or province abbreviation. example: CA countryAbbr: type: string nullable: true description: >- Two-letter country abbreviation (ISO 3166-1 alpha-2). example: US countryAlpha2: type: string nullable: true description: ISO 3166-1 alpha-2 country code. example: US countryAlpha3: type: string nullable: true description: ISO 3166-1 alpha-3 country code. example: USA countryNumeric: type: integer nullable: true description: ISO 3166-1 numeric country code. example: 840 fullString: type: string nullable: true description: Fully formatted location string. example: San Francisco, CA 94107, United States timezone: type: string nullable: true description: Timezone name with abbreviation. example: Pacific (PDT) timezoneRawOffset: type: string nullable: true description: UTC offset of the timezone in hours. example: '-8.00' timezoneAbbr: type: string nullable: true description: Timezone abbreviation. example: PDT companyLocation: type: object description: >- Headquarters or primary office address of the contact's company. properties: street1: type: string nullable: true description: Primary street address line. example: 1 Hacker Way street2: type: string nullable: true description: >- Secondary street address line (suite, floor, etc.). example: '' street3: type: string nullable: true description: Tertiary street address line. example: '' city: type: string nullable: true description: City name. example: Menlo Park state: type: string nullable: true description: Full state or province name. example: California postCode: type: string nullable: true description: Postal or ZIP code. example: '94025' county: type: string nullable: true description: County name, if available. example: '' country: type: string nullable: true description: Full country name. example: United States stateAbbr: type: string nullable: true description: Two-letter state or province abbreviation. example: CA countryAbbr: type: string nullable: true description: >- Two-letter country abbreviation (ISO 3166-1 alpha-2). example: US countryAlpha2: type: string nullable: true description: ISO 3166-1 alpha-2 country code. example: US countryAlpha3: type: string nullable: true description: ISO 3166-1 alpha-3 country code. example: USA countryNumeric: type: integer nullable: true description: ISO 3166-1 numeric country code. example: 840 fullString: type: string nullable: true description: Fully formatted address string. example: >- 1 Hacker Way, Menlo Park, CA 94025, United States city: type: string nullable: true description: >- The city where the contact is located. Flat mirror of `contactLocation.city`, provided for consistency with the search endpoint. example: Jacksonville state: type: string nullable: true description: >- The state or region where the contact is located. Flat mirror of `contactLocation.state`, provided for consistency with the search endpoint. example: Florida country: type: string nullable: true description: >- The country where the contact is located. Flat mirror of `contactLocation.country`, provided for consistency with the search endpoint. example: United States companyCity: type: string nullable: true description: >- The city where the contact's company headquarters is located. Flat mirror of `companyLocation.city`, provided for consistency with the search endpoint. example: Columbus companyState: type: string nullable: true description: >- The state or region where the contact's company headquarters is located. Flat mirror of `companyLocation.state`, provided for consistency with the search endpoint. example: Ohio companyCountry: type: string nullable: true description: >- The country where the contact's company headquarters is located. Flat mirror of `companyLocation.country`, provided for consistency with the search endpoint. example: United States timezone: type: string nullable: true description: >- The contact's local timezone (name with abbreviation). Flat mirror of `contactLocation.timezone`, consistent with the search endpoint. example: Eastern (EST) timezoneAbbr: type: string nullable: true description: >- The contact's local timezone abbreviation. Flat mirror of `contactLocation.timezoneAbbr`. example: EST localTime: type: string nullable: true format: date-time description: >- The contact's current local time when the response was generated, as an ISO 8601 timestamp with the timezone's UTC offset. example: '2026-07-16T10:32:00-04:00' website: type: string nullable: true description: Company website domain. example: acmecorp.com emailDomain: type: string nullable: true description: >- Domain portion of the contact's email address, if available. example: '' image: type: string nullable: true description: >- URL to the contact's profile photo, if available. example: '' email1: type: string nullable: true description: >- First email address found for the contact (typically the primary/selected email). example: jsmith@example.com email1Selected: type: boolean nullable: true description: >- Whether this email was selected as the primary email for the contact. example: true email1TotalAI: type: string nullable: true description: >- Confidence score (percentage) for the first email address. example: 97% email1EmailAI: type: string nullable: true description: >- Email validation status for the first email address (e.g., valid, invalid, risky). example: valid email2: type: string nullable: true description: Second email address found for the contact. example: jane.smith@example.com email2TotalAI: type: string nullable: true description: >- Confidence score (percentage) for the second email address. example: 97% email2EmailAI: type: string nullable: true description: >- Email validation status for the second email address. example: valid email3: type: string nullable: true description: Third email address found for the contact. example: janes@example.com email3TotalAI: type: string nullable: true description: >- Confidence score (percentage) for the third email address. example: 97% email3EmailAI: type: string nullable: true description: >- Email validation status for the third email address. example: valid advertisingIntelligence: type: string nullable: true description: >- URL to advertising intelligence data for the contact's company. example: http://www.moat.com/advertiser/AcmeCorp alexaScore: type: string nullable: true description: >- URL to Alexa site information for the company domain. example: http://www.alexa.com/siteinfo/acmecorp.com companyNews: type: string nullable: true description: >- URL to Google News search results for the company. example: >- https://www.google.com/search?q=Acme+Corp&tbm=nws employeeReviews: type: string nullable: true description: >- URL to Glassdoor employee reviews for the company. example: >- http://www.glassdoor.com/Reviews/Acme-Corp-reviews-SRCH_KE0,9.htm googleFinance: type: string nullable: true description: URL to Google Finance page for the company. example: http://www.google.com/finance?q=Acme+Corp googleResearch: type: string nullable: true description: >- URL to a Google search for the contact at their company. example: >- https://www.google.com/search?q=Jane+Smith+Acme+Corp jobPostings: type: string nullable: true description: URL to Glassdoor job postings for the company. example: >- http://www.glassdoor.com/Job/jobs.htm?suggestCount=0&suggestChosen=false&sc.keyword=Acme+Corp localSportsTeams: type: string nullable: true description: >- URL to a Google search for local sports teams near the company HQ. example: >- https://www.google.com/search?q=Menlo+Park+California+sports+teams localWeather: type: string nullable: true description: >- URL to a Google search for weather near the company HQ. example: >- https://www.google.com/search?q=Menlo+Park+California+weather paidSearchIntelligence: type: string nullable: true description: >- URL to SEMrush paid search data for the company domain. example: http://www.semrush.com/info/acmecorp.com paidSearchKeywordsIntelligence: type: string nullable: true description: >- URL to KeywordSpy keyword research for the company domain. example: >- http://www.keywordspy.com/research/search.aspx?q=acmecorp.com&tab=domain-overview searchMarketingIntelligence: type: string nullable: true description: >- URL to iSpionage search marketing data for the company domain. example: >- http://www.ispionage.com/research/US/acmecorp.com secFilings: type: string nullable: true description: URL to SEC EDGAR filings for the company. example: >- https://www.sec.gov/cgi-bin/browse-edgar?company=Acme+Corp&owner=exclude&action=getcompany seoResearch: type: string nullable: true description: URL to Ahrefs SEO data for the company domain. example: >- https://ahrefs.com/site-explorer/overview/subdomains?target=acmecorp.com similarWebsites: type: string nullable: true description: >- URL to find websites similar to the company domain. example: >- https://www.similarsitesearch.com/search/?URL=acmecorp.com socialMediaMentions: type: string nullable: true description: >- URL to social media mention tracking for the company domain. example: >- http://socialmention.com/search?q=acmecorp.com&t=all&btnG=Search socialMediaPosts: type: string nullable: true description: >- URL to social media post search for the company domain. example: >- http://www.social-searcher.com/social-buzz/?q5=acmecorp.com socialPosts: type: string nullable: true description: URL to blog/social post search for the contact. example: http://www.icerocket.com/search?q=Jane+Smith websiteAudit: type: string nullable: true description: >- URL to SimilarWeb traffic analysis for the company domain. example: http://www.similarweb.com/website/acmecorp.com websiteAudit2: type: string nullable: true description: >- URL to WooRank website audit for the company domain. example: https://www.woorank.com/en/www/acmecorp.com websiteGrader: type: string nullable: true description: >- URL to HubSpot Website Grader analysis for the company domain. example: https://website.grader.com/tests/acmecorp.com webTechnologies: type: string nullable: true description: >- URL to BuiltWith technology lookup for the company domain. example: https://builtwith.com/acmecorp.com whois: type: string nullable: true description: >- URL to WHOIS domain registration lookup for the company domain. example: http://www.whois.com/whois/acmecorp.com wikipedia: type: string nullable: true description: >- URL to the Wikipedia page for the company, if available. example: https://en.wikipedia.org/wiki/Acme_Corp yahooFinance: type: string nullable: true description: URL to Yahoo Finance page for the company. example: http://finance.yahoo.com/q?s=Acme+Corp formerCompany: type: string nullable: true description: >- Name of the contact's most recent previous employer. example: Previous Corp formerTitle: type: string nullable: true description: >- Job title at the contact's most recent previous employer. example: Finance Manager formerStartedAt: type: string nullable: true format: date description: >- Date the contact started at their former company (YYYY-MM-DD). example: '2014-05-01' formerEndedAt: type: string nullable: true format: date description: >- Date the contact left their former company (YYYY-MM-DD). example: '2019-01-01' titleStartedAt: type: string nullable: true format: date description: >- Date the contact started their current title (YYYY-MM-DD). example: '2019-02-01' startedAtCurrentCompany: type: string nullable: true format: date description: >- Date the contact started at their current company (YYYY-MM-DD). example: '2014-05-01' timeAtRole: description: >- Human-readable tenure in the contact's current role, derived from `titleStartedAt` (e.g. "1 Yr 2 Mo", "3 Mo"). type: string nullable: true example: 1 Yr 2 Mo timeAtCompany: type: string nullable: true description: >- Human-readable tenure at the contact's current company, derived from `startedAtCurrentCompany` (e.g. "1 Yr 2 Mo", "3 Mo"). example: 5 Yr jobHistory: type: array description: > The contact's prior roles, most recent departure first. The current role is not included here — it is carried by `companyName` (`company`), `jobTitle` (`title`), `startedAtCurrentCompany` and `titleStartedAt` — and `formerCompany`/`formerTitle` mirror the first entry. Returned by `POST /contacts/research` (via `GET /contacts/research/poll`); a contact with no known prior roles gets an empty array, never `null` or a missing key. items: type: object properties: companyName: type: string nullable: true description: Company name for this role. example: Previous Corp title: type: string nullable: true description: Job title held at that company. example: Finance Manager startedAt: type: string nullable: true format: date description: >- Date the contact started this role (YYYY-MM-DD). Null when unknown. example: '2014-05-01' endedAt: type: string format: date description: >- Date the contact left this role (YYYY-MM-DD). Always set — open-ended roles are not prior roles. example: '2019-01-01' jobChangeAlert: type: string description: > Type of job change detected given provided or default job change date range. When detected; 'New Hire' = joined a new company, 'New Promotion' = new role at the same company. enum: - New Hire - New Promotion nullable: true companyType: type: string nullable: true description: >- Company type — "Public" or "Private" when determined. enum: - Public - Private example: Public stockTicker: type: string nullable: true description: >- Stock ticker symbol of the company, if publicly traded. example: AAPL apiResearchId: type: string description: >- The request ID returned from the /contacts/research endpoint. Use this to correlate research requests with results. example: 6Ei5iKuSHzJXvqjVPWiZ_ newsAndEvents: type: array nullable: true description: Recent news articles related to the company. items: type: object properties: title: description: The headline of the news article. type: string nullable: true url: description: The URL to the full news article. type: string nullable: true date: description: The date the news article was published. type: string nullable: true format: date-time type: description: >- The type of news article (e.g., "Acquisition"). type: string nullable: true companyFundingTotal: type: string nullable: true description: The latest total funding amount for the company. example: '100000' companyLatestFundingDate: type: string nullable: true format: date description: >- The date of the latest funding round for the company (formatted as "YYYY-MM-DD"). example: '2023-08-12' companyLatestFundingClassifications: type: array nullable: true description: >- The classifications of the latest funding round for the company (e.g., "Series A", "Pre-Seed", etc.). example: - Series D items: type: string additionalData: type: object description: >- Additional metadata for the poll result (e.g., error details). Free-form object. additionalProperties: true '401': description: Unauthorized content: application/json: schema: type: object required: - message properties: message: description: A human readable error message type: string '422': description: Insufficient credits or missing license content: application/json: schema: description: Insufficient credits or missing license type: object properties: msg: type: string code: type: string data: type: object properties: productCategory: type: string additionalCreditsNeeded: type: integer '500': description: Unexpected error content: application/json: schema: type: object required: - message properties: message: description: A human readable error message type: string security: - OAuth2: [] - ApiKeyAuth: [] components: securitySchemes: OAuth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://login.seamless.ai/oauth/authorize tokenUrl: https://api.seamless.ai/api/client/v2/oauth/accessToken scopes: {} ApiKeyAuth: type: apiKey name: Token in: header description: API key passed via the Token header. ````