Skip to content

Commit 52b25c5

Browse files
AnandChowdharyAnandChowdhary
committed
docs: Add more docs for audiences & API
1 parent 3830130 commit 52b25c5

28 files changed

+1352
-142
lines changed

‎api-reference/authentication.mdx

+8-6
Original file line numberDiff line numberDiff line change
@@ -9,16 +9,18 @@ To authenticate requests, you must provide your API key or personal access token
99
"Authorization": "Bearer <API key>"
1010
```
1111

12-
## Generating an API key
13-
14-
API keys can be generated by navigating to FirstQuadrant -> Settings -> Apps and enabling "FirstQuadrant API". You will see the API key once once after enabling the API, so please make sure to copy it and store it in a safe place.
15-
16-
API keys contain the prefix `fqa_live_` and are in the format `fqa_live_<alphanumeric>:int_<alphanumeric>`.
12+
API keys contain the prefix `fqa_live_` and are in the format `fqa_live_<alphanumeric>:api_<alphanumeric>`.
1713

1814
Note that API keys are scoped to a team, so you will be unable to make requests to `/users` endpoints. If you would like to access both your user account and any teams you are associated with, use a personal access token.
1915

2016
Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly-available places such as client-side code or commit them to your repository's source code. We recommend using a secrets manager such as [Doppler](https://www.doppler.com) or [Infisical](https://infisical.com) to store your API keys.
2117

18+
## Create and manage API keys
19+
20+
To create or manage your API keys, go to **Settings** -> **Integrations** and click on "Settings" under API keys. On the API keys page, you can view and manage your existing API keys or click on "Create API key" on the top right to create a new one.
21+
22+
You can name your API key and optionally add scopes (Read or Write), IP ranges, and expiration dates. Once you create an API key, the key will be copied to your clipboard and you will have the option to download a TXT file with the key. Note that you will not be able to view the key again, so be sure to save it in a secure location. If you lose your key, you can always create a new one by clicking on "Regenerate API key" in the menu.
23+
2224
## Authorization errors
2325

24-
If you do not provide an API key or personal access token when making a request, you will receive a **401 Unauthorized** response. If your API key does not have the necessary scopes to perform an action, you will receive a **403 Forbidden** response.
26+
If you do not provide a valid API key or personal access token when making a request, you will receive a **401 Unauthorized** response. If your API key does not have the necessary scopes to perform an action, you will receive a **403 Forbidden** response.

‎api-reference/contacts/contactId/block.mdx

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: Unsubscribe a contact
3+
openapi: POST /api/teams/{teamId}/contacts/{contactId}/block
4+
---

‎api-reference/contacts/contactId/delete.mdx

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: Delete a contact
3+
openapi: DELETE /api/teams/{teamId}/contacts/{contactId}
4+
---

‎api-reference/contacts/contactId/get-campaign-contacts.mdx

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: List campaign contacts
3+
openapi: GET /api/teams/{teamId}/contacts/{contactId}/campaign-contacts
4+
---

‎api-reference/contacts/contactId/get.mdx

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: Get a contact
3+
openapi: GET /api/teams/{teamId}/contacts/{contactId}
4+
---

‎api-reference/contacts/contactId/patch.mdx

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: Update a contact
3+
openapi: PATCH /api/teams/{teamId}/contacts/{contactId}
4+
---

‎api-reference/contacts/contactId/unblock.mdx

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: Resubscribe a contact
3+
openapi: POST /api/teams/{teamId}/contacts/{contactId}/unblock
4+
---

‎api-reference/contacts/get.mdx

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: List contacts
3+
openapi: GET /api/teams/{teamId}/contacts
4+
---

‎api-reference/sdks.mdx

-23
This file was deleted.

‎api-reference/teams/conversations/post-won.mdx

-4
This file was deleted.

‎api-reference/teams/delete.mdx

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: Delete a team
3+
openapi: DELETE /api/teams/{teamId}
4+
---

‎api-reference/teams/get-me.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
---
22
title: Get the current team
3-
openapi: GET /teams/me
3+
openapi: GET /api/teams/me
44
---

‎api-reference/teams/get-outbound-settings.mdx

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: Get outbound settings
3+
openapi: GET /api/teams/{teamId}/outbound
4+
---

‎api-reference/teams/get.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
---
22
title: Get a team
3-
openapi: GET /teams/{teamId}
3+
openapi: GET /api/teams/{teamId}
44
---

‎api-reference/teams/patch-outbound-settings.mdx

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: Update outbound settings
3+
openapi: PATCH /api/teams/{teamId}/outbound
4+
---

‎api-reference/teams/patch.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
---
22
title: Update a team
3-
openapi: PATCH /teams/{teamId}
3+
openapi: PATCH /api/teams/{teamId}
44
---

‎audiences/import-csv.mdx ‎audiences/import.mdx

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
2-
title: Import CSVs
3-
description: Import an existing audience using CSVs
2+
title: Import
3+
description: Import your own CSV file to create a new audience in FirstQuadrant.
44
---
55

66
To import an existing audience, for example from your CRM, you can use a CSV (comma-separated values) file. The first row of the file should include at least the header **Contact Email**:

‎audiences/integrate.mdx

+89
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
---
2+
title: Integrate
3+
description: Send contacts from third-party tools to FirstQuadrant.
4+
---
5+
6+
You can use FirstQuadrant's integrations to send contacts from third-party tools to FirstQuadrant. This allows you to use your existing CRM, marketing automation platform, or other tools to send contacts to FirstQuadrant for further enrichment and use in your campaigns.
7+
8+
## Supported integrations
9+
10+
### Zapier
11+
12+
The easiest way to integrate FirstQuadrant with third-party tools is to use [Zapier](https://zapier.com). Zapier allows you to connect FirstQuadrant with thousands of other tools, such as CRMs, marketing automation platforms, and more, without writing any code.
13+
14+
To use Zapier, you can create an audience with the type "Integrate" and click on "Connect with Zapier" to join the beta program. Once you've joined the beta program, you can create a Zap to send contacts from your third-party tool to FirstQuadrant.
15+
16+
### Campaign API
17+
18+
Each campaign with the type "Integrate" also gets a campaign-specific, public-facing API endpoint that you can use to send contacts to FirstQuadrant. You can use this API endpoint to send contacts from your third-party tool to FirstQuadrant programmatically. For example, when someone signs up on your website, you can send their contact information to FirstQuadrant using the Campaign API.
19+
20+
The API key starts with `fqa_pub_` and is unique to each campaign. You can find the API key on the Audience page of your campaign by clicking on "Review API key". Note that this API key is different from your team's API keys, which are used for authentication when using the FirstQuadrant API. The campaign-specific API key is used to send contacts to a specific campaign and can be safely shared with third-party tools or used in client-side code (note that campaign API keys include `pub_` in the key, meaning "public", whereas others do not).
21+
22+
#### Request body
23+
24+
The API endpoint accepts an object with the properties `contact`, `company`, and `data`. The minimum required properties is `contact.email`, but it is recommended to include `contact.name` and `company.name` if available. The following properties are supported:
25+
26+
- `contact`: `name`, `email`, `apolloId`, `nickname`, `bio`, `avatar`, `website`, `location`, `timeZone`, `city`, `state`, `countryCode`, `latitude`, `longitude`, `employmentTitle`, `employmentSeniority`, `linkedInUrl`, `twitterUrl`, `facebookUrl`, `githubUrl`
27+
- `company`: `name`, `domain`, `nickname`, `bio`, `avatar`, `website`, `street`, `city`, `state`, `postalCode`, `country`, `rawAddress`, `foundedYear`, `employeesCount`, `alexaGlobalRank`, `retailLocationsCount`, `annualRevenue`, `fundingTotal`, `fundingStage`, `ticker`, `primaryIndustry`, `secondaryIndustries`, `tags`, `languages`, `techStack`, `phone`, `blogUrl`, `angelListUrl`, `linkedInUrl`, `twitterUrl`, `facebookUrl`, `crunchbaseUrl`
28+
- `data`: You can include any additional data in the `data` property as a key-value pair where both the key and the value is a string. This data will be stored with the contact and can be used in your campaigns.
29+
30+
The descriptions of these properties are the same as the properties in the [Import CSV audience](./import-csv) feature.
31+
32+
#### Authentication
33+
34+
You need to include the API key in the `Campaign-API-Key` header. If you are unable to send custom headers, you can also include the API key in the request body as `apiKey` or as a query parameter `campaign-api-key`.
35+
36+
#### Examples
37+
38+
In the following examples, you can replace `CAMPAIGN_API_KEY` with the API key of your campaign. In these examples, we're sending a contact with the name "John Doe" and email [email protected] to FirstQuadrant. They have written a custom message "I want to contact sales." which is stored in the `data.message` property.
39+
40+
You can use the following HTML form to send contacts to FirstQuadrant. Since HTML forms do not support nested objects, you can use dot notation to specify nested properties. For example, `contact.name` will be parsed as `contact: { name: "John Doe" }` when the header `Content-Type: application/x-www-form-urlencoded` is set.
41+
42+
```html
43+
<form
44+
action="https://firstquadrant.ai/api/go/audience?campaign-api-key=CAMPAIGN_API_KEY"
45+
method="post"
46+
>
47+
<label>Name <input name="contact.name" /></label>
48+
<label>Email <input name="contact.email" type="email" /></label>
49+
<label>Message <textarea name="data.message"></textarea></label>
50+
<button type="submit">Submit</button>
51+
</form>
52+
```
53+
54+
You can use the following cURL command to send contacts to FirstQuadrant:
55+
56+
```bash
57+
curl \
58+
-X POST \
59+
-H "Campaign-API-Key: CAMPAIGN_API_KEY" \
60+
-H "Content-type: application/json" \
61+
-d '{
62+
"contact": {
63+
"name": "John Doe",
64+
"email": "[email protected]"
65+
},
66+
"data": {
67+
"message": "I want to contact sales."
68+
}
69+
}' 'https://firstquadrant.ai/api/go/audience'
70+
```
71+
72+
You can use the following JavaScript code to send contacts to FirstQuadrant:
73+
74+
```js
75+
await fetch("https://firstquadrant.ai/api/go/audience", {
76+
method: "POST",
77+
headers: {
78+
"Campaign-API-Key": "CAMPAIGN_API_KEY",
79+
"Content-Type": "application/json",
80+
},
81+
body: JSON.stringify({
82+
contact: {
83+
name: "John Doe",
84+
email: "[email protected]",
85+
},
86+
data: { message: "I want to contact sales." },
87+
}),
88+
});
89+
```

‎audiences/prospect.mdx

+51
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
title: Prospect
3+
description: Find new prospects for your campaigns using FirstQuadrant's built-in tool.
4+
---
5+
6+
You can use FirstQuadrant's built-in tool to find new prospects for your campaigns. This tool allows you to search for contacts based on various criteria, such as job title, company size, industry, and location.
7+
8+
Under the hood, we use [Apollo.io](https://www.apollo.io) as the data provider for this feature and then use AI to further enrich the data. This allows you to find the most relevant contacts for your campaigns. Apollo has almost 100 million contacts in its database with verified email addresses, so you can be sure that you'll find the right prospects for your campaigns.
9+
10+
## Filters
11+
12+
You can use the following filters to find the right prospects for your campaigns.
13+
14+
### Company
15+
16+
These filters are related to the company where the contact works. You can use these filters to find contacts based on the company's size, industry, location, revenue, and funding.
17+
18+
- Company headcount
19+
- Company HQ
20+
- Industry and keywords
21+
- Revenue and funding
22+
- Funding rounds
23+
- Total funding amount
24+
- Annual revenue amount
25+
- Trading status
26+
- Advanced
27+
- Technologies
28+
- Exclude industries
29+
- Exclude locations
30+
- Open positions
31+
- Job titles
32+
- Hiring locations
33+
- Number of positions
34+
- Posted date
35+
36+
### Role and personal
37+
38+
These filters are related to the role and personal information of the contact. You can use these filters to find contacts based on their job title, management position, employer, and location.
39+
40+
- Current employment
41+
- Current job title
42+
- Management position
43+
- Current employer
44+
- Previous employments
45+
- Previous job titles
46+
- Previous employers
47+
- Department
48+
- Location
49+
- Advanced
50+
- Exclude employers
51+
- Exclude locations

‎audiences/qualification.mdx

+43
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
title: Qualification
3+
description: Use AI to further qualify your audience to hyper-target the right contacts.
4+
---
5+
6+
You can use FirstQuadrant's AI to further qualify your audience to hyper-target the right contacts. This feature allows you to find the most relevant contacts for your campaigns by using AI to enrich the data. This will help you to improve your targeting and increase your conversion rates.
7+
8+
## Default qualification criteria
9+
10+
FirstQuadrant uses the following default qualification criteria to qualify your audience.
11+
12+
### Company and contact are enriched
13+
14+
FirstQuadrant uses AI to enrich the company and contact data. This includes enriching the company data with information such as the company's size, industry, location, revenue, and funding. The contact data is enriched with information such as the contact's job title, management position, employer, and location.
15+
16+
By default, the following criteria are used to qualify your audience:
17+
18+
- **Company name is known:** The name of this company is known.
19+
- **Company website is available:** Ensure that the primary domain of the company is known and their website is currently active. This helps to ensure that the company is still in business and is a good proxy for the company's activity.
20+
- **Company description is generated:** Ensure that FirstQuadrant was able to generate a description for the company by scraping their website. This is used for personalization and to ensure that the company is relevant to your campaign.
21+
- **Name is known:** The name of the contact is known to ensure that the contact is a real person and we can personalize the outreach.
22+
- **Email address is verified:** The email address of the contact is verified to ensure that the contact is reachable.
23+
24+
Additionally, you can use the following criteria to further qualify your audience if you are using any of the following details in your Sequence and would only like to target contacts that have these details:
25+
26+
- **Current job title is known:** Ensure that the current job title of the contact is known.
27+
- **Location is known:** Ensure that the location of the contact is known.
28+
- **Work history is known:** Ensure that the work history of the contact is known.
29+
- **Personal email address is not used:** Ensure that the contact's personal email address is not used. This helps to ensure that the contact is reachable at their work email address.
30+
31+
### Exclude contacts from other campaigns
32+
33+
FirstQuadrant excludes contacts that are already in another campaign. This ensures that you don't target the same contacts multiple times and helps to prevent over-saturation. By default, all campaigns are considered when excluding contacts. You can choose to exclude contacts from specific campaigns.
34+
35+
## Filter questions
36+
37+
You can use AI to further qualify your audience by using filter questions. Filter questions are yes-no questions that help you to filter out contacts that don't meet your criteria. You can use filter questions to further qualify your audience based on very specific criteria.
38+
39+
For example, if you are a business that sells remote work software, you may only want to target companies that offer remote or hybrid work options to their employees. You can create a filter question "Does this company offer remote or hybrid work options?" and FirstQuadrant will use AI to answer this question for each contact and only include contacts that meet your criteria.
40+
41+
By default, all contacts that answer the filter question with "Yes" will be included in your audience. You can choose to include contacts that answer the filter question with "No" to filter by negative criteria.
42+
43+
Under the hood, FirstQuadrant conducts a web search to find the answer to the filter question. This is done by using AI to analyze the company's website, news articles, and other sources.

‎introduction.mdx

-10
Original file line numberDiff line numberDiff line change
@@ -24,14 +24,4 @@ Use the FirstQuadrant API to programmatically access your team, for example to m
2424
<Card title="Authentication" icon="key" href="/api-reference/authentication">
2525
Generate an API key and make your first request.
2626
</Card>
27-
<Card title="SDKs" icon="layer-group" href="/api-reference/sdks">
28-
Use our SDKs to get started quickly.
29-
</Card>
30-
<Card
31-
title="Mark conversations as won"
32-
icon="trophy"
33-
href="/api-reference/teams/conversations/post-won"
34-
>
35-
Track goal conversions on open conversations.
36-
</Card>
3727
</CardGroup>

‎mailboxes/connect.mdx

+6-2
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,10 @@ title: Connect mailboxes
33
description: FirstQuadrant will automatically provision domains and email accounts as you start and scale your campaigns. However, if you prefer to use your own domain and email accounts, you can connect them to FirstQuadrant.
44
---
55

6+
## Adding mailboxes
7+
8+
Visit **Settings** -> **Mailboxes** and click on "Connect mailboxes" to add a new mailbox. You can select from Google, Outlook, Exchange, Zoho, IMAP, or "More" if your provider is not listed.
9+
610
## Google Workspace
711

812
If you're using Google Workspace (Gmail), you will first have to enable the FirstQuadrant app for your account:
@@ -16,9 +20,9 @@ If you're using Google Workspace (Gmail), you will first have to enable the Firs
1620
7. Continue by checking the box and then selecting "Trusted" in the next step.
1721
8. Finish the set up flow, and you're done!
1822

19-
## Adding mailboxes
23+
For more information, you can visit the [Control which third-party & internal apps access Google Workspace data](https://support.google.com/a/answer/7281227) page on Google Workspace Help.
2024

21-
Visit Settings -> Mailboxes and click on "Connect mailbox" to add a new mailbox. YOu can select from Google, Outlook, Exchange, Zoho, IMAP, or "More" if your provider is not listed.
25+
## Bulk import mailboxes
2226

2327
You can also import mailboxes from a CSV file. Click on "Select file" and upload a CSV file with the following columns:
2428

0 commit comments

Comments
 (0)