Mobile App Integration

The Pelcro Open API provides RESTful endpoints for mobile app integration. Use authentication endpoints to obtain a JWT token, then include that token in protected API requests.

Base URL: https://www.pelcro.com/api/v1/sdk

Full API Reference: Open API Documentation

# Example: Login and make authenticated request

POST /api/v1/sdk/auth/login?site_id={site_id}
Content-Type: application/json

{"email": "[email protected]", "password": "password"}

# Response includes auth_token
# Store token securely in device keychain/keystore

# Use token for authenticated requests
POST /api/v1/sdk/customer?site_id={site_id}
Authorization: Bearer {auth_token}

Prerequisites

Before integrating, you need:

Authentication Flow

Mobile App → Register/Login → Receive JWT Token → Store Securely → Use in Authorization Header

Authentication Endpoints

Site & Configuration

Authentication Pattern

All protected endpoints follow a consistent authentication pattern:

Register a New User

POST /api/v1/sdk/auth/register?site_id={site_id}
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "securePassword123",
  "first_name": "John",
  "last_name": "Doe"
}

Request Body Fields:

Success Response (200 OK):

{
  "status": "success",
  "data": {
    "id": 12345,
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "auth_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "subscriptions": null,
    "addresses": null
  }
}

Login an Existing User

POST /api/v1/sdk/auth/login?site_id={site_id}
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "securePassword123"
}

Request Body Fields:

Note: Provide either email OR username, not both. After 10 failed attempts, the account is locked for 5 minutes (HTTP 429).

Success Response (200 OK):

{
  "status": "success",
  "data": {
    "id": 12345,
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "auth_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "subscriptions": [...],
    "addresses": [...]
  }
}

Store Token Securely

After successful registration or login, store the auth_token securely on the device:

• iOS: Use Keychain Services

Make Authenticated Requests

Include the token in the Authorization header for all protected endpoints:

POST /api/v1/sdk/customer?site_id={site_id}
Authorization: Bearer {auth_token}
Content-Type: application/json

Example: Get Customer Profile

POST /api/v1/sdk/customer?site_id={site_id}
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
Content-Type: application/json

Example: Update Customer Profile

PUT /api/v1/sdk/customer?site_id={site_id}
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
Content-Type: application/json

{
  "first_name": "Jane",
  "last_name": "Smith"
}

Logout

POST /api/v1/sdk/auth/logout?site_id={site_id}
Authorization: Bearer {auth_token}
Content-Type: application/json

Success Response (200 OK):

{
  "status": "success",
  "data": {
    "id": 12345,
    "email": "[email protected]"
  }
}

What Happens:

1. Token is invalidated on server (blacklisted)
2. Token cannot be used for subsequent requests
3. Clear token from device storage
4. User must login again to get new token

Token Management

Token Properties

Response Format

Success Response

All successful responses follow this structure:

{
  "status": "success",
  "data": {
    // Response data here
  }
}

Error Response

All error responses follow this structure:

{
  "error": {
    "status": 400,
    "message": "Error description here"
  }
}

Error Handling

HTTP Status Codes

Error Response Examples

Invalid Credentials (404):

{
  "error": {
    "status": 404,
    "message": "Invalid credentials! Please try again."
  }
}

Validation Error (422):

{
  "error": {
    "status": 422,
    "message": "The email has already been taken."
  }
}

Rate Limited (429):

{
  "error": {
    "status": 429,
    "message": "Too many login attempts. Please try again in 5 minutes."
  }
}

Token Expired (401):

{
  "error": {
    "status": 401,
    "message": "Token has expired."
  }
}

Security Best Practices

1. Store tokens securely - Use platform secure storage (iOS Keychain, Android Keystore/EncryptedSharedPreferences)
2. Never store tokens in plain text - Avoid SharedPreferences, UserDefaults, or plain files
3. Use HTTPS only - All API communication must be encrypted
4. Validate SSL certificates - Enable certificate validation in your HTTP client
5. Handle token expiration - Check expiration before requests and refresh when needed
6. Clear tokens on logout - Remove from secure storage completely
7. Never log tokens - Avoid printing auth tokens in debug/console logs
8. Implement certificate pinning - Optional but recommended for additional security

Complete API Reference

This guide covers the most common endpoints for mobile app integration. For the complete list of available endpoints, including advanced features like campaigns, memberships, exports, webhooks, and more, refer to the Open API Documentation.

Quick Start Checklist

Additional Resources

• Open API Introduction

For support, contact: [email protected]