Skip to main content

​
Welcome

The Nex Developer API provides programmatic access to your organizational context. Generate API keys from the Nex web UI and use them to authenticate requests.

Nex API Specification

View the complete OpenAPI specification

​
Authentication

All API endpoints are authenticated using API keys. Include your API key in the Authorization header: 
Authorization: Bearer YOUR_API_KEY

​
Base URL

All API requests should be made to: 
https://app.nex.ai/api/developers

​
Scopes

Each API key has specific scopes that control what operations it can perform. Request the scopes you need when generating your API key.
ScopeDescription
object.readRead object definitions and their attributes
object.writeCreate, update, and delete object definitions, attributes, and lists
record.readRead records, search, and view timelines
record.writeCreate, update, and delete records and list memberships
list.readRead list definitions
list.member.readRead list members and records
list.member.writeAdd, update, and remove list members
relationship.readRead relationship definitions
relationship.writeCreate and delete relationship definitions and instances
task.readRead tasks
task.writeCreate, update, and delete tasks
note.readRead notes
note.writeCreate, update, and delete notes
integration.readList integrations and check connection status
integration.writeConnect and disconnect integrations
insight.streamSSE insight streaming

​
Data Model Overview

Nex uses an Entity-Attribute-Value (EAV) model that provides flexible data storage for different types of records. This architecture allows you to:
  • Define custom object types (entity definitions) with their own attributes
  • Create records (entities) that conform to these definitions
  • Store attribute values that can be of various types (text, email, relationships, etc.)
  • Define relationships between object types
  • Track activity with tasks, notes, and timeline events

​
Core Resources

​
Objects (Entity Definitions)

Objects define the structure and schema for your data types. Think of them as “templates” or “blueprints” for creating records. Default Objects:
  • Person: Individual contacts with attributes like name, email, job title, company relationships
  • Company: Organization records with attributes like name, domain, industry, team relationships
You can also create custom object types (e.g., “Project”, “Deal”) and define their attributes via the Schema endpoints.

​
Records (Entities)

Records are instances of your object definitions - the actual data entries in your workspace. Example Person Record Response: 
{
  "id": "789",
  "object_id": "123",
  "type": "person",
  "workspace_id": "456",
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-20T14:30:00Z",
  "attributes": {
    "name": "John Smith",
    "email_addresses": ["john@example.com", "j.smith@company.com"],
    "job_title": "Software Engineer"
  }
}
Note: For many attribute types like full_name, phone, and location, you can use either simple string values (e.g., "John Smith") or structured objects (e.g., {"first_name": "John", "last_name": "Smith"}). The API accepts both formats.

​
Relationships

Relationships define how object types relate to each other (e.g., Person → Company). You can create relationship definitions between any two object types, then create instances linking specific records. Relationship types: one_to_one, one_to_many, many_to_many

​
Lists

Lists allow you to organize and group records for campaigns, segments, or any custom categorization. Lists are associated with specific object types.

​
Tasks

Tasks are actionable items that can be associated with records and assigned to users. Tasks support priorities (low, medium, high, urgent), due dates, and completion tracking. Deleting a task archives it (soft delete).

​
Notes

Notes are free-form text entries that can be associated with records. Deleting a note archives it (soft delete).

​
Timeline

The timeline provides a chronological activity feed for any record, including tasks, notes, attribute changes, and relationship events. Supports cursor-based pagination.

​
Integrations

Integrations connect your workspace to third-party services like Gmail, Google Calendar, Outlook, Slack, and CRM platforms. Use the OAuth flow to connect accounts, then Nex automatically syncs data into your workspace. Supported integrations:
TypeProviderName
emailgoogleGmail
calendargoogleGoogle Calendar
emailmicrosoftOutlook
calendarmicrosoftOutlook Calendar
messagingslackSlack
crmattioAttio
crmhubspotHubSpot
crmsalesforceSalesforce
OAuth flow:
  1. Call POST /v1/integrations/{type}/{provider}/connect to get an auth_url and connect_id
  2. Open the auth_url in a browser for the user to authorize
  3. Poll GET /v1/integrations/connect/{connect_id}/status until status is "connected"
Full-text search across all records in the workspace. Results are grouped by object type and include relevance scores.

​
Attribute Types

When creating attributes via the Schema endpoints, the following types are supported:
TypeDescription
textFree-form text
numberNumeric values (integer or decimal)
emailEmail addresses
phonePhone numbers
urlURLs
dateDates
booleanTrue/false values
currencyCurrency amounts
locationPhysical addresses
selectPredefined options (single or multi-select)
social_profileSocial media profiles
domainWeb domains
full_nameStructured names (first/last)

​
Pagination

The API uses two pagination styles:
  • Offset-based: Used by records, tasks, and list records. Responses include total, limit, offset, and has_more/next_offset fields.
  • Cursor-based: Used by timeline. Responses include has_next_page and next_cursor fields.

​
Error Handling

All error responses follow a consistent format: 
{
  "code": 400,
  "message": "Description of what went wrong"
}
Status CodeDescription
400Bad request - Invalid input data
401Unauthorized - Invalid or missing API key
404Not found - Resource doesn’t exist
429Too many requests - Rate limit exceeded
500Internal server error

​
Common Use Cases

  • Contact Management: Create and update person and company records
  • Schema Customization: Define custom object types and attributes
  • Relationship Mapping: Link people to companies and track team structures
  • List Management: Organize contacts into targeted lists for campaigns
  • Task Tracking: Create follow-up tasks associated with contacts
  • Note Taking: Attach meeting notes and context to records
  • Activity Feed: View the complete timeline of changes for any record
  • Search: Find records across your entire workspace
  • Data Enrichment: Update records with additional information from external sources
  • AI Context: Add unstructured context and query your data with natural language
Last modified on March 7, 2026