Connection intelligence, built into your product.

Overview

Give your product a superconnector

Your product already has the people. Nexus gives it the intelligence to understand how they should connect.

Search your entire network in plain English. Find the best people for any individual. Rank mentors against founders, investors against companies, members against opportunities, or any other relationship your product needs to understand.

Nexus does the hard part: understanding context, relevance, complementary needs, expertise and connection potential. Your application decides where that intelligence appears and what happens next.

Instead of building and maintaining your own people-search infrastructure, embedding pipeline, ranking logic, matching models and explanation layer, you make an API call. Nexus returns your own IDs, ranked by relevance, with a plain-English reason explaining each result.

Three endpoints cover the whole surface.

Your system stays the source of truth

You do not move your product into Nexus. Your system remains the source of truth for your users and your business logic.

Nexus maintains the intelligence required to search and match the profile information you choose to provide. Every result comes back using the external_id from your system, so it maps directly into the product you already have.

Your dataset stays isolated

Your partner dataset is private to your integration. It does not appear on public or guest Nexus pages, it is not included in any Nexus community search, and it is not used in Nexus campaigns. It can only be read with your partner API key.

Nexus returns your identifiers, never its own internal IDs.

Use cases

What connection intelligence lets you build

These are examples, not product constraints. Nexus returns connection intelligence through the API; how you use it is entirely up to you.

1. Natural-language people search

Turn any directory, marketplace or network into intelligent search. A user can type:

• "Fintech founders who have sold into large banks"
• "Investors interested in climate hardware"
• "Someone who has scaled a marketplace in Latin America"

Nexus understands the intent, ranks the people in your network and explains why each result is relevant. One /search request. No search syntax for the user to learn.

On your side, render each result straight from display and reason, and show display_score as the badge. Because the reason is generated from the person's own synced fields, it doubles as the card's subtitle.

2. Personalized "people you should meet"

Give every user recommendations that feel hand-picked. Pass Nexus a person and receive the strongest connections for them, ranked by relevance and accompanied by an explanation of why the two people should connect.

Use it for member recommendations, founder and investor discovery, internal experts, networking, customer communities, professional marketplaces or advisor discovery. It can power a recommendation feed, a profile sidebar, a weekly email, an introduction workflow or anything else you build.

One /match request with the person's id in whole-dataset mode returns the top limit people with a reason for each.

3. Intelligent matching at scale

Power structured matching without reducing people to tags and filters.

• Mentors ↔ founders
• Advisors ↔ companies
• Buyers ↔ suppliers
• Investors ↔ startups
• New members ↔ established members

Your application controls hard eligibility rules such as geography, availability, language, programme or capacity. Nexus handles the harder question: out of everyone who is eligible, who is actually the best match? Send Nexus the candidate IDs and it ranks the pairings and explains each one.

Technically: filter to the eligible ids on your side, send them as candidate_external_ids to /match, apply your own threshold to relevance, and write the outcome to your own matches table. Nothing is stored on the Nexus side, so you can re-run whenever the roster changes.

4. Smarter onboarding from day one

A new user should not have to spend weeks discovering who matters. As soon as somebody joins your product, Nexus can identify the people most relevant to them and explain why.

Use those results for "people you should meet", suggested mentors, relevant investors, recommended experts, useful peers or a personalized welcome email.

A newly synced member is available for matching immediately after a successful sync, so onboarding recommendations can happen in the same workflow: sync, then /match, in one job.

5. Understand the intelligence inside your entire networkEarly access

Search tells you who matches a question. Match tells you who should connect with a person. The Nexus knowledge graph goes one level higher: it helps your product understand the network itself.

• What does this group collectively know?
• What are people trying to accomplish?
• Where is demand concentrated?
• Where does relevant expertise exist?
• Which valuable connections have not happened yet?

Nexus maps topics, industries, organizations, expertise, needs and opportunities across the people you provide, then returns that intelligence using your own identifiers. Use it to build network analytics, identify unmet demand, surface opportunities or automatically create high-value introductions.

Contact Nexus to enable knowledge graph access for your partner account.

Authentication

One API key. That's it.

Every Partner API request uses your server-side partner API key in the x-partner-api-key header. Nexus provides the key when your partner account is provisioned and delivers it out of band. Keep it server-side and you are ready to make authenticated requests. There is no query-string or body alternative, and no self-service key management.

curl -X POST https://www.nexus.app/api/partner/{partner}/match \  -H "x-partner-api-key: $NEXUS_PARTNER_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "subject_external_id": "acme-1042" }'

The key is compared in constant time. A missing or incorrect key returns 401 with the standard error envelope and the code unauthorized. Authentication is checked before anything else, so an unauthenticated call never consumes budget and never touches your data.

Conventions

Simple, predictable API behavior

The Partner API is deliberately small. Three POST endpoints, JSON request bodies, JSON responses and one authentication header.

Base URL and transport

All endpoints are served over HTTPS from https://www.nexus.app. Every endpoint is a POST with a JSON body and returns JSON. Send Content-Type: application/json. Responses are computed per request and never cached.

Every path contains a partner segment, shown here as {partner}. It is the slug assigned to your tenant at provisioning and is confirmed alongside your key. Paths are otherwise identical for every partner.

Error envelope

Every non-2xx response has the same shape: an error object with a machine-readable code and a human-readable message. Branch on the code, never on the message.

{
  "error": {
    "code": "missing_query",
    "message": "query is required."
  }
}

Budget responses add one top-level field, retry_after_seconds, the number of seconds until the daily budget resets.

{
  "error": {
    "code": "search_cap_exceeded",
    "message": "Daily search budget reached."
  },
  "retry_after_seconds": 18342
}

Order of checks

Each endpoint evaluates a request in the same order. Knowing it explains which error you see first.

1. Authentication. A bad key returns 401 immediately.
2. Daily budget. An exhausted budget returns 429.
3. Body validation. A missing or invalid field returns 400.
4. Tenant lookup. A partner tenant that is not provisioned returns 500 with partner_group_missing.
5. The work itself.

Malformed and unknown input

A body that is not valid JSON is treated as an empty body, so you receive the endpoint's "required field missing" error rather than a parse error. Unknown fields in a request are ignored. String inputs are trimmed before validation, so a value of only whitespace counts as missing.

Idempotency and state

Sync is idempotent: replaying the same batch produces the same dataset. Search and match are stateless reads. Nexus stores nothing per call beyond an anonymous daily counter, so re-running either is always safe.

Endpoint 1

Sync members

Give Nexus the people and context its connection intelligence should reason over.

Create, update or remove up to 200 people per request using the stable external_id from your own system. Once a record is successfully indexed, it is immediately available to search and match.

Request body

The body is an object with one key, members, holding 1 to 200 record objects. Each record has the fields below. Anything not listed is ignored.

{
  "members": [
    {
      "external_id": "acme-1042",
      "email": "priya.raman@example.com",
      "first_name": "Priya",
      "last_name": "Raman",
      "title": "Co-founder & CTO",
      "organization": "Northwind Grid",
      "about": "Building battery storage for rural micro-grids.",
      "match_context": "Pre-seed. Wants a power-electronics advisor and hardware angel intros.",
      "skills": ["embedded systems", "power electronics"],
      "interests": ["climate tech", "hardware fundraising"],
      "city": "Nairobi",
      "country": "Kenya",
      "linkedin": "https://www.linkedin.com/in/priya-raman-example",
      "website": "northwindgrid.example.com",
      "status": "active"
    },
    {
      "external_id": "acme-0871",
      "email": "tomas.lindqvist@example.com",
      "status": "removed"
    }
  ]
}

How a record is applied

Nexus first looks for a member in your dataset with the same external_id. If none exists, it looks for a person with the same email. What happens next depends on what it finds.

• Nobody found. A new member is created from the record and reported as created.
• A person that only your dataset knows. Your record is the source of truth: name and profile fields are overwritten verbatim and the skills and interests lists are replaced.
• A person who also exists elsewhere on Nexus. The membership in your dataset is attached, only fields that are currently empty are filled, tags are added rather than replaced, and the person's name is left alone. The result carries linked_existing_user: true.

In both of the last two cases the result is created when the person was not previously in your dataset and updated when they were. After every record in the batch has been applied, each created or updated member is re-indexed before the response is sent, so a successful result is searchable and matchable as soon as the call returns.

A status: "removed" record deletes the person's membership in your dataset. Removal is idempotent: removing someone who is not in your dataset still reports removed. Removing an external_id and email Nexus has never seen is rejected with not_found. Re-sending a removed person as active restores them.

Each record is applied in its own transaction. A record that fails is reported as rejected and the rest of the batch continues.

Response

{
  "batch_id": "6f1c9c2e-3b7a-4d0e-9a1b-2c3d4e5f6a7b",
  "results": [
    {
      "external_id": "acme-1042",
      "status": "created",
      "embedding": "refreshed"
    },
    {
      "external_id": "acme-0871",
      "status": "removed",
      "embedding": "skipped"
    }
  ],
  "summary": {
    "created": 1,
    "updated": 0,
    "removed": 1,
    "rejected": 0
  }
}

Two more shapes a result entry can take:

{
  "external_id": "acme-2210",
  "status": "updated",
  "linked_existing_user": true,
  "warnings": [
    "title truncated to 100 characters",
    "linkedin dropped: not a linkedin.com/in/ profile URL"
  ],
  "embedding": "failed"
}

{
  "external_id": "acme-3305",
  "status": "rejected",
  "code": "invalid_email",
  "message": "email \"not-an-address\" is not a valid address."
}

Rejection codes

A rejected record never fails the batch. The HTTP status is still 200 and the other records are applied.

• invalid_payloadThe record is not a JSON object.
• missing_external_idexternal_id is absent or empty.
• missing_emailemail is absent or empty.
• invalid_emailemail does not look like an address.
• invalid_statusstatus is something other than "active" or "removed".
• not_foundA removal named a person Nexus has never seen.
• internal_errorThe record failed to process. Its transaction was rolled back; the rest of the batch continued.

Errors

Endpoint 2

Search

Ask your network a question in plain English.

Send Nexus what the user is looking for and receive the most relevant people in ranked order. Queries can be broad, "people who understand enterprise healthcare sales", or highly specific, "climate fintech founders in Nairobi".

Nexus interprets the intent, applies supported structured constraints and ranks the strongest results. Each result can include a plain-English explanation of why that person matched.

Request body

{
  "query": "climate fintech founders in Nairobi",
  "limit": 5,
  "include_reasons": true,
  "candidate_external_ids": ["acme-1042", "acme-1187", "acme-1201", "acme-1344"]
}

The candidate fence is the mechanism for scoping: run your own deterministic filter first, send the eligible ids, and Nexus ranks only inside that set. If none of the supplied ids resolve, the response is 200 with an empty results array.

Response

{
  "query": "climate fintech founders in Nairobi",
  "applied_filters": [
    {
      "id": "location:city:Nairobi",
      "type": "location",
      "field": "city",
      "operator": "eq",
      "value": "Nairobi",
      "values": ["nairobi"],
      "label": "City: Nairobi"
    }
  ],
  "results": [
    {
      "external_id": "acme-1187",
      "type": "person",
      "rank": 1,
      "relevance": 0.8123,
      "display_score": 9,
      "reason": "Amara runs a pay-as-you-go solar financing startup in Nairobi and lists climate finance as a core skill.",
      "reason_source": "llm",
      "display": {
        "name": "Amara Okonkwo",
        "title": "Founder & CEO",
        "organization": "SunLedger",
        "location": "Nairobi, Kenya",
        "tags": ["Climate Finance", "Mobile Payments", "Angel Investing"],
        "avatar_url": "https://cdn.example.com/avatars/acme-1187.png"
      }
    },
    {
      "external_id": "acme-1042",
      "type": "person",
      "rank": 2,
      "relevance": 0.7409,
      "display_score": 8,
      "reason": "Matches on Nairobi and climate tech.",
      "reason_source": "evidence",
      "display": {
        "name": "Priya Raman",
        "title": "Co-founder & CTO",
        "organization": "Northwind Grid",
        "location": "Nairobi, Kenya",
        "tags": ["Embedded Systems", "Power Electronics", "Climate Tech", "Hardware Fundraising"],
        "avatar_url": "https://cdn.example.com/avatars/acme-1042.png"
      }
    }
  ]
}

{
  "query": "climate fintech founders in Nairobi",
  "applied_filters": [],
  "results": []
}

Reasons never cause an error. If the model-written reasons are unavailable, or your daily reasons budget is exhausted, every result still carries a deterministic sentence with reason_source: "evidence". Ranking is never affected by reasons.

Errors

Endpoint 3

Match

Find the right connections for any person.

Give Nexus one person, the subject, and it ranks the people most relevant to them. Nexus looks at the context available for both sides of the relationship and returns the strongest pairings, with a relevance score and a clear explanation of why each connection makes sense.

Search answers "who fits this request?". Match answers "who should this person meet?". You can let Nexus rank across the full dataset, or pass a specific eligible group and have Nexus rank only those people.

Request body

{
  "subject_external_id": "acme-1042",
  "candidate_external_ids": ["acme-1187", "acme-2210", "acme-1042", "acme-9999"],
  "include_reasons": true
}

{
  "subject_external_id": "acme-1042",
  "limit": 10
}

Match everyone, or only the people you allow

• Whole dataset (candidate_external_ids omitted). Let Nexus find the strongest connections from everyone available. Nexus ranks every eligible member of your dataset, excluding the subject, and returns the top limit. unmatched is always empty in this mode.
• Your candidate set (candidate_external_ids supplied). Apply your own eligibility rules first, then let Nexus rank everyone who remains. Nexus ranks exactly that list. Every requested id appears either in results or in unmatched with a code. Nothing is silently dropped, and limit does not apply.

Ranking is deterministic: the same people with the same synced data produce the same order. Ties are broken in a stable order.

# 1. Your eligibility rules pick who is allowed to be matched.eligible_ids = pool.filter(p => p.accepting && p.languages.includes(person.language)) # 2. Nexus ranks exactly that list and explains each pairing.POST /api/partner/{partner}/match{ "subject_external_id": person.id, "candidate_external_ids": eligible_ids } # 3. Your threshold decides what gets surfaced. Store the outcome on your side.matches = response.results.filter(r => r.relevance >= YOUR_MIN_SCORE).slice(0, 3)

Response

{
  "subject_external_id": "acme-1042",
  "results": [
    {
      "external_id": "acme-1187",
      "rank": 1,
      "relevance": 0.6934,
      "reason": "Both are building climate-focused companies in Nairobi, and Amara's experience raising for hardware-adjacent products speaks to Priya's stated fundraising need.",
      "reason_source": "llm",
      "display": {
        "name": "Amara Okonkwo",
        "title": "Founder & CEO",
        "organization": "SunLedger",
        "location": "Nairobi, Kenya",
        "tags": ["Climate Finance", "Mobile Payments", "Angel Investing"],
        "avatar_url": "https://cdn.example.com/avatars/acme-1187.png"
      }
    }
  ],
  "unmatched": [
    { "external_id": "acme-1042", "code": "is_subject" },
    { "external_id": "acme-2210", "code": "no_embedding" },
    { "external_id": "acme-9999", "code": "unknown_external_id" }
  ]
}

Codes in unmatched:

• is_subjectThe candidate is the subject.
• unknown_external_idNo member of your dataset has this id.
• not_searchableThe member exists but is not currently eligible to appear in results.
• no_embeddingThe member has not been indexed yet. Re-sync the record; a successful sync reports embedding: "refreshed".

Note the differences from search: match results carry no type and no display_score, and the deterministic reason source is overlap rather than evidence. As with search, reasons degrade to the deterministic sentence and never cause an error.

Errors

Limits

Clear limits. Predictable behavior.

Request sizes

Daily budgets

Each endpoint has a budget of calls per UTC day. Budgets reset at 00:00 UTC, and a 429 tells you exactly how long to wait in retry_after_seconds. Budgets are counted per endpoint for your tenant, not per IP address.

The values above are the current defaults.

Errors

Errors

Consistent error handling across every endpoint.

HTTP-level errors use the envelope described under Conventions. Per-record sync rejections arrive inside a 200 body and are listed under Sync.

Retry guidance: 429 after retry_after_seconds; 500 on search and match immediately, since both are stateless; 500 on sync by re-sending the batch, since every record is idempotent and records that already committed are unaffected. Never retry a 400, 401, 404 or 422 without changing the request.

Operations

Production behavior

Everything below is what you need to know about timeouts, freshness, identifiers and retries when running the Partner API in production.

Timeouts

A sync call indexes every created or updated member before it responds, one at a time, so a full batch of 200 can take minutes. The sync handler may run for up to 300 seconds; set your client timeout at least that high, and prefer smaller batches when you need faster feedback. Search and match handlers may run for up to 60 seconds; typical responses are far quicker, and sending include_reasons: false removes the slowest step.

Freshness

A member whose sync result reports embedding: "refreshed" is live in search and match the moment the call returns. A member reporting embedding: "failed" keeps their previous index state until you re-send the record. A removed member disappears from both surfaces immediately.

Identifiers

Stable external_id values are load-bearing. Nexus matches by id first and by email second, so an id that changes on your side creates a second person on the next sync. If ids can change, say so before go-live.

What is never returned

No Nexus internal identifiers, no email addresses, no raw synced text other than what appears in display and the reason sentence, and no member who is not in your dataset. Search and match responses only ever contain people carrying one of your external ids.

Support

Quote the batch_id from a sync response when reporting a sync problem. It lets Nexus find the exact batch, its per-record outcomes and its timing.