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

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": "Missing phone number",
  "data": {
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "reason": "Missing phone number"
  }
}

Other Rejections

All other errors (invalid phone, carrier, duplicate, email, 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:

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
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	Missing phone number	`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
200	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`	❌ No	Missing phone number - fix the data and resubmit
`200` (rejected)	❌ No	Validation error, duplicate, or processing issue
`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.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