# Goma API

> Real-time people data in one call. Send a public LinkedIn profile URL, get a normalized,
> structured profile back. Credit-metered: one successful lookup costs one credit; failed lookups are
> never charged.

## Docs
- API reference (interactive): https://trygoma.com/docs
- OpenAPI 3.1 spec: https://trygoma.com/openapi.json

## Authentication
- Bearer API key: `Authorization: Bearer gma_live_…`. Create and manage keys in the dashboard.

## Endpoints
- GET /api/v1/person/profile?url=<linkedin-profile-url> — returns a normalized public profile
  ({ data, meta }). data.current_position lists every current role; data.insights.job_change
  is { type: "new_title" | "new_company", title, company_name, company_linkedin_url, start_month
  ("YYYY-MM") } when a current role started in the last 3 months (as of the call), else null.
  Cost: 1 credit on success. Errors return { error: { code, message, request_id } } with codes: invalid_request, unauthenticated, insufficient_credits, profile_not_found,
  rate_limited, service_unavailable, internal_error.

## Recipe: check a campaign list before it goes out

Paste this into your agent (Claude Code, Cursor, n8n AI step, or your own) with your API key in `GOMA_API_KEY`:

```text
I have a CSV of contacts for an outbound campaign. Each row has a LinkedIn profile URL plus the company and title I have on record.

Check every row against the Goma API before the campaign goes out:
- For each row, call GET https://trygoma.com/api/v1/person/profile?url=<linkedin_url> with the header "Authorization: Bearer $GOMA_API_KEY". Run up to 5 requests at a time.
- Compare my company and title with data.current_position. A person can hold several current roles, so match against any of them. Treat small differences ("Inc" vs none, "VP" vs "Vice President") as the same.
- Add a status column to each row:
  - in_role: same company, same title
  - title_changed: same company, different title (put the new title in new_title)
  - moved: no current role at my company (put their current company and title in new_company and new_title)
  - not_found: the API returned 404 profile_not_found (the profile is gone; no credit was charged)
- If the API returns 402 insufficient_credits, stop and tell me how many rows are left. On 429 or 503, wait a few seconds and retry that row once.
- Write the results to a new CSV and give me a count per status.
```

Each found profile costs 1 credit; not-found rows are free. Your 500 free signup credits cover a 500-row list.