nurturally.io API Reference

Explore our API endpoints and integrate nurturally.io into your applications.

🔐

Authentication

Sign In

POST

Authenticate a user with their credentials. This endpoint returns a JWT token that can be used for subsequent authenticated requests.

Endpoint

POST /api/auth/signin

Request Body

{ "email": "string", "password": "string" }
# Request
curl -X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '
{ "email": "user@example.com", "password": "your-password" }
' \
https://api.nurturally.io/api/auth/signin
# Response
{ "status": "success", "message": "Operation completed successfully" }

Sign Up

POST

Create a new user account. After successful registration, you'll receive a confirmation email with further instructions.

Endpoint

POST /api/auth/signup

Request Body

{ "name": "string", "email": "string", "password": "string" }
# Request
curl -X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '
{ "name": "John Doe", "email": "john@example.com", "password": "secure-password" }
' \
https://api.nurturally.io/api/auth/signup
# Response
{ "status": "success", "message": "Operation completed successfully" }
🔄

OAuth2 Integration

Authorization

GET

Start the OAuth2 flow by redirecting users to our authorization endpoint. Users will be prompted to log in and approve your application's access request.

Endpoint

GET /oauth/authorize

Query Parameters

{ "client_id": "Your client ID", "redirect_uri": "Your registered callback URL", "scope": "Space-separated list of scopes", "state": "Random string for CSRF protection" }
# Request
curl -X GET \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://api.nurturally.io/oauth/authorize?client_id=your_client_id&redirect_uri=https://your-app.com/callback&scope=read write&state=random_state
# Response
{ "status": "success", "message": "Operation completed successfully" }

Token Exchange

POST

Exchange the authorization code for an API key. This endpoint should be called from your backend to keep your client secret secure.

Endpoint

POST /oauth/token

Request Body

{ "code": "Authorization code from callback", "client_id": "Your client ID", "client_secret": "Your client secret" }
# Request
curl -X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '
{ "code": "authorization_code", "client_id": "your_client_id", "client_secret": "your_client_secret" }
' \
https://api.nurturally.io/oauth/token
# Response
{ "status": "success", "message": "Operation completed successfully" }

Using API Keys

Once you have an API key, include it in all API requests using the Authorization header. API keys are scope-restricted and can be revoked at any time.

Example Request

Authorization Bearer your_api_key

Available Scopes

{ "read": "Read access to user data", "write": "Write access to user data", "admin": "Full administrative access" }
# Request
curl -X GET \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://api.nurturally.io/api/resource
# Response
{ "status": "success", "message": "Operation completed successfully" }

Error Handling

OAuth and API endpoints return standard error responses when something goes wrong. Always check the error response for details about what went wrong.

Common Errors

{ "invalid_client": { "error": "Invalid client credentials", "status": 401 }, "invalid_code": { "error": "Invalid authorization code", "status": 400 }, "invalid_scope": { "error": "Insufficient scope", "requiredScope": "write", "providedScopes": [ "read" ], "status": 403 } }
👥

Leads

List All Leads

GET

Retrieve a paginated list of leads. You can filter and sort the results using query parameters.

Endpoint

GET /api/leads

Query Parameters

{ "page": "number", "limit": "number", "search": "string", "sortField": "string", "sortOrder": "asc | desc" }
# Request
curl -X GET \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://api.nurturally.io/api/leads?page=1&limit=10
# Response
{ "status": "success", "message": "Operation completed successfully" }

Create Lead

POST

Create a new lead in the system. All fields are required except for notes.

Endpoint

POST /api/leads

Request Body

{ "firstName": "string", "lastName": "string", "email": "string", "company": "string", "notes": "string" }
# Request
curl -X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '
{ "firstName": "Jane", "lastName": "Smith", "email": "jane@company.com", "company": "Tech Corp", "notes": "Interested in enterprise plan" }
' \
https://api.nurturally.io/api/leads
# Response
{ "status": "success", "message": "Operation completed successfully" }
🔑

API Keys

API keys are used to authenticate requests to the external API. Each key is associated with a user account and has specific permissions.

Create API Key

POST

Generate a new API key with specific permissions and expiration date.

Endpoint

POST /api/keys

Request Body

{ "name": "string", "expiresAt": "string (ISO date)", "permissions": "string[]" }
# Request
curl -X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '
{ "name": "Production API Key", "expiresAt": "2024-12-31T23:59:59Z", "permissions": [ "read:leads", "write:leads" ] }
' \
https://api.nurturally.io/api/keys
# Response
{ "status": "success", "message": "Operation completed successfully" }
🌐

External API

The external API allows third-party applications to interact with the nurturally.io platform. All requests must include a valid API key in the Authorization header.

Authentication

Include your API key in the Authorization header of all requests:

Authorization: Bearer YOUR_API_KEY
# Request
curl -X GET \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://api.nurturally.io/api/ext/leads
# Response
{ "status": "success", "message": "Operation completed successfully" }
🔍

Discovered Partners

List Discovered Partners

GET

Retrieve a list of discovered partners with their confidence scores and probabilities. Partners are automatically classified as either leads or partners based on their interaction patterns.

Endpoint

GET /api/partners/discovered

Response

{ "partners": [ { "id": "partner_id", "name": "John Doe", "email": "john@example.com", "confidence": 0.85, "partnerProbability": 0.75, "leadProbability": 0.25, "emailCount": 5, "lastContact": "2024-03-15T12:00:00Z", "matchDetails": { "referralIntent": [ "make an introduction", "connect you with" ], "positiveIntent": [ "looking forward to", "great opportunity" ] } } ] }

Score Interpretation

  • confidence: Overall match confidence (0-1)
  • partnerProbability: Likelihood of being a partner (0-1)
  • leadProbability: Likelihood of being a lead (0-1)

The higher probability between partnerProbability and leadProbability determines the recommended classification. These scores are calculated based on interaction patterns, message content, and engagement signals.

# Request
curl -X GET \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://api.nurturally.io/api/partners/discovered
# Response
{ "status": "success", "message": "Operation completed successfully" }

Import Partners

POST

Import discovered partners into your main partners list. You can override the automatic classification by specifying the partnerType.

Endpoint

POST /api/partners/import

Request Body

{ "emails": [ "john@example.com", "jane@example.com" ], "partnerType": "PARTNER" }

Notes

  • If partnerType is not specified, the system will use the higher probability score to determine the type
  • Imported partners are removed from the discovered partners list
  • Duplicate partners are prevented through email uniqueness constraints
# Request
curl -X POST \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '
{ "emails": [ "john@example.com" ], "partnerType": "PARTNER" }
' \
https://api.nurturally.io/api/partners/import
# Response
{ "status": "success", "message": "Operation completed successfully" }