List Management API Documentation

Complete reference for integrating with the Noesis List Management API

Quick Start

Get started quickly with a simple cURL request:

curl -X POST https://x.noesistechnology.com/list-management/feed \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cellPhone": "5551234567",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "zip": "90210",
    "subid": "campaign123"
  }'

The List Management API allows you to submit lead data for processing through our list management system.

Getting your API Key: Contact your account manager to obtain your API key. You can provide it as either an Authorization header or a query parameter.

Authentication

Authenticate your requests using one of these methods:

Option 1: Authorization Header (Recommended)

Authorization: YOUR_API_KEY

Option 2: Query Parameter

?api_key=YOUR_API_KEY

Security Note: Treat your API keys like passwords. Never expose them in client-side code or public repositories.

Endpoint & Request

Base URL

https://x.noesistechnology.com

Endpoint

POST /list-management/feed

Headers

Header	Required	Description
`Content-Type`	Yes	Must be `application/json`
`Authorization`	Yes*	Your API key (*or use query param)

Example Request

curl -X POST https://x.noesistechnology.com/list-management/feed \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cellPhone": "5551234567",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "zip": "90210",
    "state": "CA",
    "city": "Los Angeles",
    "address": "123 Main Street",
    "dob": "1990-01-15",
    "subid": "campaign123",
    "ip": "192.168.1.1",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
  }'

Request Body

Parameter	Type	Required	Description
`cellPhone`	string	Yes	US phone number (10 or 11 digits)
`firstName`	string	No	First name
`lastName`	string	No	Last name
`email`	string	No	Email address
`zip`	string	No	ZIP code
`state`	string	No	State (2-letter code)
`city`	string	No	City
`address`	string	No	Street address
`dob`	string	No	Date of birth (YYYY-MM-DD)
`subid`	string	No	Tracking sub-identifier
`ip`	string	No	IP address of the user
`userAgent`	string	No	User agent string from browser
`age`	string/number	No	Age (or calculated from DOB)
`gender`	string	No	Gender
`source`	string	No	Lead source identifier

Alternate Field Names

The API accepts multiple naming conventions for the same field:

Field	Accepted Names
Phone	`cellPhone`, `phone`, `cellphone`, `mobile`
First Name	`firstName`, `first_name`
Last Name	`lastName`, `last_name`
ZIP	`zip`, `zipcode`, `zip_code`
DOB	`dob`, `dateOfBirth`, `date_of_birth`
Sub ID	`subid`, `sub_id`, `subId`
Click ID	`clickId`, `click_id`, `clickid`
IP	`ip`, `ip_address`
User Agent	`userAgent`, `user_agent`

Custom Fields: Any additional fields not listed above are passed through and stored with the lead record.

Note: Additional fields may be required based on your list configuration. Contact your account manager for details.

Responses

All responses follow this envelope structure:

{
  "success": boolean,
  "message": string,
  "data": {
    "requestId": string,
    "reason": string (optional)
  }
}

Success Response

200 OK

{
  "success": true,
  "message": "Successfully sent",
  "data": {
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Error Responses

Common error responses you may encounter:

Authentication Error

401 Unauthorized

{
  "success": false,
  "message": "Invalid API key",
  "data": {
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "reason": "Invalid API key"
  }
}

Validation Errors

400 Bad Request

{
  "success": false,
  "message": "Invalid phone number",
  "data": {
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "reason": "Invalid phone number"
  }
}

Reject Reasons

Common reject reasons you may encounter:

HTTP Status	Reason	Description
200	Invalid phone number	Not valid US number, disconnected, landline, or lookup fail
200	Record could not be processed	Temporary Error
201	Duplicate submission detected within 24-hour window	Same number submitted within last 24 hours
201	Phone number is on global opt-out list	Number has opted out of receiving messages
400	Missing phone number	`cellPhone` field missing from request
400	Carrier not allowed	Phone carrier is not in the accepted list
400	Unknown carrier	Carrier could not be identified for the phone number
400	Invalid email format	Email field provided but format invalid

Error Handling & Retry

Retry Guidelines

Error Type	Should Retry?	Notes
`401 Unauthorized`	❌ No	Check your API key
`400 Bad Request` (validation)	❌ No	Fix the data and resubmit
`400 Bad Request` (duplicate)	❌ No	Duplicate submissions are blocked
`500 Internal Server Error`	✅ Yes	Wait 2-5 seconds, then retry once

Request Tracking: Every response includes a unique requestId. Save this ID for tracking submissions, debugging issues, and support requests.

Status Codes

Status Code	Description
200	Success - Lead accepted
400	Bad Request - Validation error
401	Unauthorized - Invalid API key
500	Internal Server Error - System error

Rate Limits

Contact your account manager for rate limit information specific to your API key.

Support

For assistance with the API:

Include the requestId from the response in all support requests
Contact your account representative
Telegram: @davidacimovic

Changelog

Version	Date	Changes
`2.0.0`	2025-02-16	Added alternate field names, carrier rejection errors
`1.0.0`	2025-01-28	Initial release

On this page