Quickstart

This quickstart calls get_current_user, an operation with no input arguments that returns the authenticated FirstTouch user and team context.

Before You Start

You need:

A Public API key created in Settings > MCP & API.
A server-side terminal or application that can send HTTPS requests.
Access to FirstTouch.

See Authentication before creating a production integration.

Make The Request

export FIRSTTOUCH_API_KEY="<key from your secrets manager>"

curl --request POST \
  --url "https://gateway.firsttouch.ai/api/public/tools/get_current_user" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: ${FIRSTTOUCH_API_KEY}" \
  --data '{}'

$env:FIRSTTOUCH_API_KEY = "<key from your secrets manager>"

$headers = @{
  "Content-Type" = "application/json"
  "X-API-Key" = $env:FIRSTTOUCH_API_KEY
}

Invoke-RestMethod `
  -Method Post `
  -Uri "https://gateway.firsttouch.ai/api/public/tools/get_current_user" `
  -Headers $headers `
  -Body "{}"

Inspect The Response

The response is normal JSON. This illustrative excerpt uses synthetic values and omits other fields; it is not a captured production response:

{
  "isAuthenticated": true,
  "userId": "example-user-id",
  "userName": "Alex Chen",
  "teamId": "example-team-id",
  "teamName": "Example Team",
  "warnings": []
}

Check these fields before continuing:

Field	What to check
`isAuthenticated`	The caller is authenticated.
`userId` and `teamId`	The returned identity and team match the intended integration context.
`permissions`	Review `isAdmin`, `isTeamOwner`, `senderEntitlement`, and `billingAccessEnabled` alongside the chosen operation’s requirements.
`warnings`	Inspect any warnings before proceeding.

The full schema also includes summary, userEmail, and availableTeams. Identity and team fields can be null; do not assume they are always populated. See the get_current_user reference and canonical OpenAPI document for the complete response schema.

Keep the environment variable in your local shell or deployment secret store. Do not put the real key directly into a script committed to source control.

Verify A Read-Only Workflow

After the identity check, try these calls with the same header and base URL. They inspect existing workspace data without creating outreach.

Step	Operation and JSON body	Use the result
Check capabilities	`get_auth_scopes` with `{}`	Review `scopes` and `warnings` for the intended workflow.
Load guidance	`get_guide` with `{"topic":"flow_plan_creation"}`	The result is Markdown text. Over HTTP it is a JSON string; decode JSON once before reading the guide.
List one Flow Plan	`list_flow_plans` with `{"limit":1}`	Read the returned `items` array. An empty array is a valid result.
Inspect that plan	`get_flow_workspace` with `{"flowPlanId":"<items[0].id>","awaitingLimit":1}`	Substitute the exact returned `items[0].id`. Review `validation`, `readiness`, and `nextSteps`; do not publish or enroll contacts as part of this check.

To read another page, call list_flow_plans again with {"limit":1,"cursor":"<returned cursor>"}, keeping the same filters and sorting. Treat cursors as opaque strings; stop when no cursor is returned. Skip the workspace call when the list is empty. The result shape depends on the operation: get_current_user returns an object, while get_guide returns a string. Avoid a client wrapper that assumes every successful result contains data, items, or success.

Call Another Operation

Use the operation catalog to select a method by workflow.
Review its description, prerequisites, input schema, permissions, and costs in the live contract.
Send a JSON object matching that schema to /api/public/tools/<tool_name>.
Inspect the operation result and any returned identifiers before deciding the next step.

For agent integrations, start with Agent Start Here.

Common Responses

Status	Meaning
`200`	An operation result was returned. Inspect it for accepted, pending, blocked, or completed work; it does not by itself confirm an outreach action finished.
`400`	The JSON body is malformed or does not pass validation.
`401`	The API key is missing, invalid, rotated, or revoked.
`403`	The key owner does not have permission for the operation.
`404`	The requested FirstTouch resource was not found.
`409`	The operation conflicts with current workflow state.
`429`	The request was rate limited. Follow returned guidance and the operation’s retry rules.
`499`	The client canceled the request. Inspect any possible write outcome before repeating it.
`500`	A server error occurred. Inspect the outcome and operation-specific recovery guidance before retrying a write.

See execution and recovery for write receipts, pending approval tasks, and ambiguous failures. In particular, never automatically retry send_linkedin_unibox_message. If contacting support, include the operation, timestamp, HTTP status, and traceId if supplied, with credentials removed.

Troubleshooting

If a request returns 401:

Confirm the header name is exactly X-API-Key.
Confirm the key is active and has not been rotated.
Confirm the creator is still active in the key’s team.
Make sure your HTTP client is not sending the key to a different host.

If a request returns 403, verify the creator’s current team role, feature access, and product entitlement in FirstTouch.

OpenAPI

Use the live contract for code generation or inspection:

https://gateway.firsttouch.ai/api/public/openapi.json

The live contract is the source for operation names, descriptions, and request and response schemas. It can change as the FirstTouch operation catalog evolves.

Start Here

Web App

Public API

Chrome Extension

References

Before You Start

Make The Request

Inspect The Response

Verify A Read-Only Workflow

Call Another Operation

Common Responses

Troubleshooting

OpenAPI

​Before You Start

​Make The Request

​Inspect The Response

​Verify A Read-Only Workflow

​Call Another Operation

​Common Responses

​Troubleshooting

​OpenAPI

Before You Start

Make The Request

Inspect The Response

Verify A Read-Only Workflow

Call Another Operation

Common Responses

Troubleshooting

OpenAPI