How do I authenticate API calls?

Include 'Authorization: Bearer YOUR_API_KEY' in the HTTP headers.

What rate limits apply?

1,000 requests per minute per workspace API key.

Are official SDKs available?

Yes, official SDKs are published for Node.js (npm), Python (PyPI), and PHP (Composer).

What format are responses returned in?

All API endpoints return standard JSON responses.

Can I trigger Lead Scraper via API?

Yes, POST /v1/scraper/create dispatches scraper jobs programmatically.

Can I request Geo-Grid rank scans via API?

Yes, POST /v1/geogrid/scan triggers coordinate grid rank scans.

Are webhooks supported?

Yes, register webhook listener endpoints in Automation -> Webhooks or via API.

Is there a sandbox endpoint for testing?

Yes, use https://sandbox.api.mapscrapx.com/v1 for testing with mock data.

How are API errors formatted?

API errors return standard JSON: { 'error': true, 'code': 'invalid_parameter', 'message': '...' }

Can I manage CRM deals via API?

Yes, GET/POST/PUT endpoints are available under /v1/crm.

Can I generate AI content via API?

Yes, POST /v1/ai/generate executes AI templates with BYOK credentials.

What IP addresses should I whitelist?

MAPSCRAPX API requests originate from static egress IPs listed in /docs/api/ips.

Is OpenAPI / Swagger spec provided?

Yes, download the full OpenAPI 3.0 JSON spec at https://api.mapscrapx.com/v1/openapi.json.

Can I revoke API keys?

Yes, instantly revoke or rotate keys under Settings -> API Keys.

DocsAPI DocumentationMAPSCRAPX REST API & SDK Reference

API Documentation15 min read 10 minutes setup Standard platform credit usage via API calls

MAPSCRAPX REST API & SDK Reference

Developer reference for REST API endpoints, bearer token authentication, rate limits, and JSON responses.

Last updated: 2026-07-26•Platform Version: v2.5.0

MAPSCRAPX REST API & SDK Reference — Official Video Tutorial

Watch this 3-minute video walkthrough to learn setup, parameters, and workflow best practices.

Overview

The MAPSCRAPX REST API enables programmatic access to all platform features. Use it to create scraper jobs, fetch leads, manage GBP profiles, generate AI content, and sync with external systems.

Authentication & Bearer Tokens

All REST API requests require a Bearer Token in the HTTP Authorization header. Generate API keys from Settings → API Keys.

bash

curl -X GET https://api.mapscrapx.com/v1/leads \
  -H 'Authorization: Bearer ms_live_secret_key_88921'

Who Should Use This Tool

Software Engineers

Full-Stack Developers

Automation Architects

DevOps Engineers

Requirements & Specifications

Credit Cost

Standard API credits required per extraction/scan

Required Fields

API Requirements

Bearer Secret API Key (ms_live_...)

Optional Fields

Required Input Fields

Field Name	Purpose	Required	Example Value	Validation & Tips
Authorization Header	Authenticate REST API requests	Required	Bearer ms_live_secret_key_88921	Valid Bearer Token format Keep API keys secure. Do not commit keys to public repositories.

Output Data Schema

Output Property	Data Type	Description	Sample Value
status_code	number	Standard HTTP response code (200, 400, 401, 429, 500)	200
data	object/array	JSON payload containing requested record results	{}
rate_limit_remaining	number	Count of API requests remaining in current minute window	984

End-to-End Workflow

Generate API Key

Navigate to Settings -> API Keys and click 'Create Secret Key'

Outcome: Secret key ms_live_... displayed

Send POST Scraper Request

Execute cURL or SDK method with query & location parameters

Outcome: JSON response returns job_id

Listen for Webhook

Receive POST payload on job completion

Outcome: Enriched leads ingested into custom app

Troubleshooting Guide

Problem: HTTP 401 Unauthorized

Root Cause: Missing or invalid Bearer token in Authorization header

Solution: Ensure header format is 'Authorization: Bearer YOUR_API_KEY'.

Problem: HTTP 429 Rate Limited

Root Cause: Exceeded 1,000 requests per minute threshold

Solution: Implement exponential backoff or contact sales for custom rate limit.

Credits, Quotas & Rate Limits

Credit Cost:

0 credits for API calls | Standard tool execution credit costs apply

Monthly Limits:

1,000 requests per minute rate limit

Rate Limit:

1,000 requests per minute per workspace key

Recommendation:

Use Webhooks for async job completion events instead of polling endpoints.

REST API Reference

GEThttps://api.mapscrapx.com/v1/leads

// cURL Request

bash

curl -X GET "https://api.mapscrapx.com/v1/leads?limit=10" \
  -H "Authorization: Bearer ms_live_secret_key_88921"

// JSON Response Payload

json

{
  "total": 1240,
  "page": 1,
  "limit": 10,
  "leads": [
    {"id": "lead_991", "business_name": "Tampa HVAC Pro", "phone": "+18135550192"}
  ]
}

Frequently Asked Questions (15)

Click to expand

https://api.mapscrapx.com/v1

Related Tools

Webhooks Engine

Configure automated HTTP POST event listeners.

Admin API Controls

Manage developer keys and usage quotas.

Tool Release History

v2.5.0Published OpenAPI 3.0 spec, Node.js SDK v2.5, and webhook HMAC signature headers.

2026-07-26

15 min read•Last Updated: 2026-07-26

Was this documentation article helpful?

Field Name

Purpose

Required

Example Value

Validation & Tips

Authorization Header

Authenticate REST API requests

Required

Bearer ms_live_secret_key_88921

Valid Bearer Token format

Keep API keys secure. Do not commit keys to public repositories.

Output Property

Data Type

Description

Sample Value

status_code

number

Standard HTTP response code (200, 400, 401, 429, 500)

200

data

object/array

JSON payload containing requested record results

{}

rate_limit_remaining

number

Count of API requests remaining in current minute window

984

End-to-End Workflow

Generate API Key

Navigate to Settings -> API Keys and click 'Create Secret Key'

Outcome: Secret key ms_live_... displayed

Send POST Scraper Request

Execute cURL or SDK method with query & location parameters

Outcome: JSON response returns job_id

Listen for Webhook

Receive POST payload on job completion

Outcome: Enriched leads ingested into custom app

Troubleshooting Guide

Problem: HTTP 401 Unauthorized

Root Cause: Missing or invalid Bearer token in Authorization header

Solution: Ensure header format is 'Authorization: Bearer YOUR_API_KEY'.

Problem: HTTP 429 Rate Limited

Root Cause: Exceeded 1,000 requests per minute threshold

Solution: Implement exponential backoff or contact sales for custom rate limit.

REST API Reference

GEThttps://api.mapscrapx.com/v1/leads

// cURL Request

bash

curl -X GET "https://api.mapscrapx.com/v1/leads?limit=10" \
  -H "Authorization: Bearer ms_live_secret_key_88921"

// JSON Response Payload

json

{
  "total": 1240,
  "page": 1,
  "limit": 10,
  "leads": [
    {"id": "lead_991", "business_name": "Tampa HVAC Pro", "phone": "+18135550192"}
  ]
}