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": "Beverly Hills",
    "address": "123 Main Street",
    "dob": "1990-01-15",
    "subid": "campaign123",
    "ip": "203.0.113.7",
    "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 digits, or 11 with a leading 1. Spaces and punctuation are ignored
`firstName`	string	No	First name
`lastName`	string	No	Last name
`email`	string	No	Email address
`zip`	string	No	5-digit US ZIP code (ZIP+4 is accepted)
`state`	string	No	State (2-letter code). Taken from `zip` when the ZIP is valid
`city`	string	No	City. Taken from `zip` when the ZIP is valid
`address`	string	No	Street address
`dob`	string	No	Date of birth, YYYY-MM-DD (MM/DD/YYYY is also accepted). Ages 18 to 110
`subid`	string	No	Tracking sub-identifier
`ip`	string	No	IP address of the user (IPv4 or IPv6)
`userAgent`	string	No	User agent string from browser

Optional fields never reject a lead: a value that fails its check (an email that is not an address, a ZIP that does not exist, a date of birth outside ages 18 to 110) is left out, and the rest of the lead is accepted.

Alternate Field Names

Field names are matched without regard to case, underscores or hyphens, so firstName, first_name and FirstName are the same field. These names are accepted:

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

Custom Fields: Any other field you send is stored with the lead as a custom field: up to 20 per lead, with names made of letters, digits, _ or - and text or number values of up to 256 characters.

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

201 Created

{
  "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"
  }
}

Missing Phone Number

400 Bad Request

{
  "success": false,
  "message": "Phone number is required",
  "data": {
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "reason": "Phone number is required"
  }
}

Other Rejections

All other errors (invalid phone, carrier, duplicate, opt-out, processing) return 200 with success: false.

200 OK

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

Internal Server Error

500 Internal Server Error

{
  "success": false,
  "message": "Internal processing error",
  "data": {
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "reason": "Internal processing error"
  }
}

Reject Reasons

Common reject reasons you may encounter. Match on the start of the reason: some carry detail after it, such as Duplicate submission detected within current day or Carrier not allowed - only AT&T, Verizon, T-Mobile accepted.

HTTP Status	Reason	Description
200	Invalid phone number	Not valid US number, disconnected, landline, or lookup fail
200	Invalid phone format	Not 10 digits, or 11 digits starting with 1
200	Phone number could not be verified	The number could not be checked in time. It can be submitted again later
200	Record could not be processed	The lead was not accepted for a reason that is not itemized
200	Duplicate submission detected	Same number already submitted within the configured dedup window
200	Phone number is on global opt-out list	Number has opted out of receiving messages
400	Phone number is required	`cellPhone` field missing from request
200	Carrier not allowed	Phone carrier is not in the accepted list
200	Unknown carrier	Carrier could not be identified for the phone number

Error Handling & Retry

Retry Guidelines

Error Type	Should Retry?	Notes
`401 Unauthorized`	❌ No	Check your API key
`400 Bad Request`	❌ No	Missing phone number - fix the data and resubmit
`200` (rejected)	❌ No	Validation error, duplicate, or processing issue. The one exception is `Phone number could not be verified`, which can be submitted again later
`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
201	Created - Lead accepted and processed
200	Rejected - Validation error, duplicate, or processing error
400	Bad Request - Missing phone number
401	Unauthorized - Invalid or missing 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.2.0`	2026-11-03	Optional fields are checked and never reject a lead (the "Invalid email format" rejection is gone), city and state are taken from the ZIP, custom fields are limited to 20 per lead, `age` and `gender` removed from the request body
`2.1.0`	2026-02-16	Configurable dedup window per list, opt-out checking enabled, data enrichment
`2.0.0`	2025-02-16	Added alternate field names, carrier rejection errors
`1.0.0`	2025-01-28	Initial release

On this page