Getting Started

Your First API Call

3 min read

Send a real enrichment request, parse the envelope, and learn the safe pattern every Renidly integration should follow.

You already have an API key (if not, start with Authentication). This page walks through one complete request — what to send, what you get back, how to read it, and what to do when something fails.

1Send the request

We'll resolve a person by handle. The full Node example below covers the safe pattern: read the key from the environment, check success before touching data, surface errors on failure.

import "dotenv/config";

const KEY = process.env.RENIDLY_API_KEY!;
const BASE = "https://renidly.com/api/v2";

const url = new URL(`${BASE}/person/enrich`);
url.searchParams.set("handle", "jane-doe");

const res = await fetch(url, {
  headers: { "X-renidly-apikey": KEY },
});

const body = await res.json();

if (!body.success) {
  // Single source of truth — the envelope tells you why.
  console.error(body.statusCode, body.message, body.errors);
  process.exit(1);
}

const { data } = body;
console.log(data.entityId, data.handle, data.headline);

2Read the response

A successful response returns the full enrichment record inside data:

{
  "success": true,
  "statusCode": 200,
  "message": "Data retrieved successfully",
  "errors": null,
  "data": {
    "entityId": "ABC123XYZ",
    "id": 902341,
    "handle": "jane-doe",
    "firstName": "Jane",
    "lastName": "Doe",
    "headline": "Head of Marketing at Acme",
    "summary": "...",
    "currentPositions": [
      { "title": "Head of Marketing", "company": "Acme" }
    ],
    "geo": { "country": "United States", "city": "San Francisco" },
    "followerCount": 12480,
    "connectionsCount": 500
  }
}

Common top-level fields

Field	What it gives you
data.entityId	Stable opaque identifier — safe to persist in your database.
data.handle	Public URL slug for the person.
data.firstName / lastName	Split name fields, normalised across locales.
data.headline	Short professional tagline (current role + company).
data.summary	Long-form bio, free text — may be empty.
data.currentPositions	Array of currently held roles, freshest first.
data.geo	Resolved location object — country, region, city.
data.followerCount	Public follower count, integer.

The full schema (every field, including localisations and historical positions) is documented in the interactive endpoint reference behind the dashboard.

3Handle errors

If the request is malformed, the response body comes back with success: false and the reason in message. No credits are charged on validation failure.

{
  "success": false,
  "statusCode": 200,
  "message": "either 'entityId' or 'handle' parameter is required",
  "errors": null,
  "data": null
}

Two failure shapes exist — general (errors: null, reason in message) and per-field validation (errors is a { field: reason } map). See Response Envelope for both, and Errors & Retries for the full taxonomy and what to do about each.

← Previous

Authentication

API Keys & Workspaces