Oppy API — reference
Base URL https://api.oppyone.com/api/public/v1. Every endpoint except /health
needs a key — see Getting started for authentication,
scopes, rate limits and error shapes.
Examples below use the environment set up there:
export OPPY_KEY="oppy_live_..."
export OPPY="https://api.oppyone.com/api/public/v1"
Cards
GET /cards
Scope: cards:read
Your workspace's cards, best first — hot, then warm, and within each tier the strongest signals first. The first page holds the most valuable cards in your workspace, so page for volume rather than for quality.
Use card_status=pending for the inbox, and approved_family for everything
approved or later — the same set the dashboard's My Approvals tab shows.
| Parameter | Notes |
|---|---|
card_status | Repeatable. pending, approved, contacted, replied, meeting_booked, closed, rejected, or approved_family for all five post-approval statuses. |
card_type | Repeatable. hot or warm; any other value returns 422. Narrows the set; it does not reorder it. |
created_from, created_to | ISO dates, inclusive. |
limit | Default 25, max 100. Above 100 returns 422 rather than silently capping. |
offset | Default 0. Latency is flat to the end of the set. |
curl -s "$OPPY/cards?card_status=pending&limit=2" \
-H "Authorization: Bearer $OPPY_KEY"
{
"data": [
{
"id": "9a69c44b-e8d4-44d7-8e46-897aa99a6c13",
"card_status": "pending",
"signal_type": "hiring-trends",
"card_type": "warm",
"title": "Northwind is hiring across GTM",
"trigger_text": "Composite hiring signal (1/3 evidence) fired 2026-05-22, hiring a CRO/Sales role",
"relevance_text": "They match your ICP on size and stack, and a CRO hire usually precedes outbound scaling...",
"strategy_text": "Nurture the Head of Sales/Founder with a light-touch note on how a CRO hire often precedes outbound scaling...",
"company_name": "Northwind",
"company_website": "northwind.example",
"company_linkedin_url": null,
"company_country": "United States",
"company_industries": ["Software Development"],
"source_url": "https://...",
"assigned_to": "sam@your-company.example",
"created_at": "2026-07-29T09:14:02",
"visible_from": null
}
],
"pagination": { "limit": 2, "offset": 0, "total": 17930, "has_more": true }
}
Cards are created with trigger_text, relevance_text and strategy_text
already written. assigned_to is an email — Oppy never exposes internal user ids.
GET /cards/{card_id}
Scope: cards:read
One card, same shape. No side effects — it will never charge anything.
POST /cards/{card_id}/approve
Scope: cards:review or cards:write
Moves the card to approved and starts the contact lookup for that company.
Reveals nothing and spends no credits. Takes no body.
curl -s -X POST "$OPPY/cards/$CARD/approve" -H "Authorization: Bearer $OPPY_KEY"
# -> the card object with "card_status": "approved"
POST /cards/{card_id}/reject
Scope: cards:review or cards:write
Body is optional. A reason feeds your ICP refinement, so it is worth sending.
curl -s -X POST "$OPPY/cards/$CARD/reject" \
-H "Authorization: Bearer $OPPY_KEY" -H "Content-Type: application/json" \
-d '{"reason": "not our ICP - too small", "category": "wrong_size"}'
# -> the card object with "card_status": "rejected"
PATCH /cards/{card_id}
Scope: cards:write
Move a card along your pipeline, or reassign it.
curl -s -X PATCH "$OPPY/cards/$CARD" \
-H "Authorization: Bearer $OPPY_KEY" -H "Content-Type: application/json" \
-d '{"card_status": "contacted", "assigned_to": "sam@your-company.example"}'
Accepts contacted, replied, meeting_booked, closed, and an assigned_to
email from GET /users — or null to unassign. It rejects approved and
rejected with a 422; those have their own endpoints because they do more than
set a field.
Contacts
GET /cards/{card_id}/contact-candidates
Scope: contacts:read · Free
Who could be revealed at this card's company. Names and titles only — email and phone are withheld until you pay for one.
curl -s "$OPPY/cards/$CARD/contact-candidates" -H "Authorization: Bearer $OPPY_KEY"
[
{
"id": "d32f25a4-f1fa-4656-93b3-58059292f01a",
"full_name": "Alex",
"title": "Founder and CEO",
"email": null,
"phone": null,
"linkedin_url": null,
"revealed": false
},
{
"id": "ef2db80c-dd82-4c50-962b-baecc9318e0a",
"full_name": "Gabriella",
"title": "Sales Professional",
"revealed": false
}
]
An empty list usually means the card is not approved yet. Approving triggers the lookup, which takes about a minute. If another card for the same company was approved earlier, candidates are there immediately. Poll this endpoint after approving — it costs nothing.
The id here is the candidate_id you pass to reveal. Surnames appear only after
the reveal, which is why the first name alone is shown.
POST /cards/{card_id}/contacts/reveal
Scope: contacts:write · Spends credits
1 credit for email and LinkedIn, 5 more if you ask for the phone. Revealing the same person again costs nothing.
| Body field | Notes |
|---|---|
candidate_id | Required for signal cards — pick one from contact-candidates. Omit for intent cards, which carry one known contact. |
include_phone | Default false. True adds 5 credits. |
curl -s -X POST "$OPPY/cards/$CARD/contacts/reveal" \
-H "Authorization: Bearer $OPPY_KEY" -H "Content-Type: application/json" \
-d '{"candidate_id": "d32f25a4-f1fa-4656-93b3-58059292f01a", "include_phone": false}'
{
"contact": {
"id": "c35fddcc-67f9-4aeb-a73f-2199c195dbf7",
"full_name": "Alex Rivera",
"title": "Founder and CEO",
"email": "alex.rivera@northwind.example",
"phone": null,
"linkedin_url": "https://linkedin.com/in/...",
"revealed": true
},
"credits_used": 1,
"credits_remaining": 82
}
Revealing approves the card. If it was still in your inbox, paying for a
contact moves it to approved — spending a credit is a stronger signal than
clicking approve, so the card should not stay pending.
With include_phone set to true the response carries a phone value and
"credits_used": 6. If no phone is found you are not charged for one.
GET /cards/{card_id}/contacts
Scope: contacts:read · Free
Contacts already paid for on this card, with full details. Use this to re-read what you own without spending anything.
[
{
"full_name": "Alex Rivera",
"email": "alex.rivera@northwind.example",
"phone": "+1 555 0100",
"revealed": true
}
]
CRM
POST /cards/{card_id}/push-to-crm
Scope: crm:write
Creates the contact and company in your CRM and attaches a note carrying the
card's context. Goes to every CRM you have connected; add ?provider=attio or
?provider=hubspot to target one. Takes no body.
curl -s -X POST "$OPPY/cards/$CARD/push-to-crm" -H "Authorization: Bearer $OPPY_KEY"
{
"card_id": "02319a25-caca-42aa-9a97-6755f74bdbc2",
"results": [
{
"provider": "attio",
"status": "pushed",
"person_record_id": "6c4f56bb-3627-4c19-b12c-d84a3bbea9d0",
"company_record_id": "7593548b-3133-4ac0-a195-e2d2cb1a184c",
"note_id": "5e52b1df-3460-40fb-b57b-e4a765fa4913",
"person_web_url": "https://app.attio.com/your-workspace/person/6c4f56bb-...",
"company_web_url": "https://app.attio.com/your-workspace/company/7593548b-...",
"hs_contact_id": null,
"error": null
},
{
"provider": "hubspot",
"status": "failed",
"hs_contact_id": null,
"error": "HubSpot token is invalid or revoked; reconnect HubSpot in the dashboard"
}
]
}
Requires a revealed contact. Without one you get a 400 telling you to reveal first. Nothing is charged.
Per-provider results. pushed, queued or failed. queued is a success —
a HubSpot outage is retried automatically rather than dropped. One CRM failing
never hides a push that succeeded in the other; the whole call fails with a 502
only when every CRM does. The example above returned 200 with Attio succeeding and
a revoked HubSpot token failing.
Ownership follows whoever the card is assigned to, if that person exists in
your CRM — a user in HubSpot, the oppy_owner attribute in Attio. It is set when
the record is created and never reassigned by a later push. Pushing the same card
twice upserts; it does not duplicate.
Workspace
| Endpoint | Returns | Scope |
|---|---|---|
GET /workspace | id, name, website, industry | workspace:read |
GET /users | email, name, status — the emails valid for assigned_to | workspace:read |
GET /credits | used, limit, remaining | workspace:read |
GET /health | {"status": "ok"} — no key needed | — |
Support & Troubleshooting
- Questions or issues: contact@oppyone.com — include the
request_idfrom the error envelope. - Authentication, scopes, rate limits and status codes are covered in Getting started.
- An interactive schema browser is available at
/api/public/v1/docs.