Getting Started

Your First API Call

3 min read

Send a real lookup 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 Node example 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/data/v1";

const url = new URL(`${BASE}/people/profile`);
url.searchParams.set("handle", "ryanroslansky");

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.id, data.handle, data.headline);

2Read the response

A successful response returns the record inside data:

{
  "success": true,
  "statusCode": 200,
  "message": "Profile retrieved successfully",
  "errors": null,
  "data": {
    "id": "prsn_06d0d44dogo2m",
    "handle": "ryanroslansky",
    "first_name": "Ryan",
    "last_name": "Roslansky",
    "headline": "...",
    "summary": "...",
    "geo_city": "San Francisco Bay Area",
    "geo_country": "United States",
    "full_positions": [ /* roles, freshest first */ ]
  }
}

A few of the top-level fields

Field	What it gives you
data.id	Stable opaque identifier (prsn_…) — safe to persist; prefer it over handle.
data.handle	Public profile slug. Can change — use id to re-fetch.
data.first_name / last_name	Split name fields.
data.headline	Short professional tagline.
data.summary	Long-form bio, free text — may be empty.
data.geo_city / geo_country	Resolved location.
data.full_positions	Work history, freshest first.

The complete schema — every field this endpoint can return — is in the interactive endpoint reference behind the dashboard. That's the source of truth for an endpoint's exact inputs and outputs.

3Handle errors

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

{
  "success": false,
  "statusCode": 400,
  "message": "either 'id' or 'handle' 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.

← Previous

Authentication

API Keys & Workspaces