Applications

The applications endpoints provide functionality for managing merchant applications for payment processing services. The model represents a complex business application with multiple nested sections that capture all required information for merchant underwriting.

Example Application Object

{
  "id": 123,
  "uniqueId": "app_01h2x35c6j2a3k8d5n6p7q8r9s",
  "leadId": 42,
  "repcode": "REP123",
  "accountId": "acct_123456",
  "createdBy": "agent@example.com",
  "updatedBy": "agent@example.com",
  "createdAt": "2023-06-01T09:00:00Z",
  "updatedAt": "2023-06-15T14:30:00Z",
  "basics": {
    "dbaName": "Acme Coffee Shop",
    "legalName": "Acme Enterprises LLC",
    "dbaContact": "John Smith",
    "dbaEmail": "contact@acmecoffee.example.com",
    "dbaPhone": "+15555555555",
    "dbaStreet1": "123 Main St",
    "dbaStreet2": "Suite 101",
    "dbaCity": "Portland",
    "dbaState": "OR",
    "dbaZip": "97201",
    "dbaTaxID": "REDACTED",
    "dbaStruct": "LLC",
    "dbaTraded": "No",
    "locationDifferent": false,
    "primaryLanguage": "English",
    "tinType": "EIN"
  },
  "businessDetails": {
    "b2BSalesPercent": 25,
    "publicSalesPercent": 75,
    "mccCategory": "Food and Beverage",
    "mccNumber": "5812",
    "website": "https://acmecoffee.example.com",
    "productsServicesSold": "Coffee, pastries, sandwiches",
    "seasonalMerchantBool": false,
    "industryType": "Restaurant"
  },
  "businessHistory": {
    "yearsInBiz": 2,
    "monthsInBiz": 6,
    "openDate": "2021-01-15",
    "previousCcProcessor": "Square",
    "creditAcceptHistoryBool": "Yes",
    "bankruptcyBool": false,
    "cardAcceptTerminationBool": false,
    "chargebacksLastYear": 0,
    "chargebackTotalAmount": 0
  },
  "businessBanking": {
    "bankName": "First National Bank",
    "bankContact": "Jane Brown",
    "bankRouting": "123456789",
    "bankAccount": "REDACTED"
  },
  "orderProcessing": {
    "cardSwipePercent": 90,
    "cardKeyedPercent": 10,
    "cardMoToPercent": 0,
    "cardInternetPercent": 0,
    "cardAcceptanceMethods": "In-Person",
    "cardDescriptor": "ACME COFFEE",
    "customerServicePhone": "+15555555556",
    "customerServiceEmail": "customer@service.com",
    "refundPolicy": "Full refund within 14 days",
    "serviceOnly": false
  },
  "scheduleABasics": {
    "avgCreditCardSales": 5000,
    "avgSaleAmount": 15,
    "maxSaleAmount": 100,
    "highMonthlyVolume": 7500
  },
  "system": {
    "appStatus": "pending",
    "submitted": false,
    "appKey": "ak_01h2x35c6j2a3k8d5n6p7q8r9t"
  },
  "businessOwners": [
    {
      "id": 1,
      "firstName": "John",
      "lastName": "Smith",
      "titlePosition": "CEO",
      "emailAddress": "john@acmecoffee.example.com",
      "cellPhone": "+15555555557",
      "equityOwnership": 100,
      "controllingInterestBool": true,
      "applicantBool": true,
      "socialSecurityNumber": "REDACTED",
      "dateOfBirth": "REDACTED"
    }
  ],
  "auditLog": [
    {
      "id": 1001,
      "event": "application_created",
      "user": "agent@example.com",
      "apiKey": null,
      "data": {
        "applicationId": "app_01h2x35c6j2a3k8d5n6p7q8r9s"
      },
      "created": "2023-06-01T09:00:00Z",
      "requestMethod": "POST",
      "requestPath": "/api/applications",
      "requestHeaders": {
        "content-type": "application/json",
        "x-account-id": "acct_123456"
      },
      "requestIpAddress": "192.168.1.50",
      "account_id": "acct_123456"
    }
  ]
}

Properties

Core Application Properties

id

• Type: integer
• Description: The unique identifier for the application in the database.
• Required: Auto-generated

uniqueId

• Type: string
• Description: A unique string identifier for the application used in URLs and external references.
• Required: Auto-generated

leadId

• Type: integer | null
• Description: The ID of a lead associated with this application, if any.
• Required: No

repcode

• Type: string
• Description: The representative code associated with this application.
• Required: Yes
• Default: Inherits from account ID if not provided

accountId

• Type: string
• Description: The account ID that this application belongs to.
• Required: Yes

createdBy

• Type: string
• Description: The email address of the user who created the application.
• Required: Yes (set automatically from session)

updatedBy

• Type: string
• Description: The email address of the user who last updated the application.
• Required: Yes (set automatically from session)

createdAt

• Type: string (ISO 8601 datetime)
• Description: The timestamp of when the application was created.
• Required: Auto-generated

updatedAt

• Type: string (ISO 8601 datetime)
• Description: The timestamp of the last update to the application.
• Required: Auto-generated

Business Basics

basics.dbaName

• Type: string | null
• Description: The “Doing Business As” name of the merchant.
• Required: No

basics.legalName

• Type: string | null
• Description: The legal entity name of the business.
• Required: No

basics.dbaContact

• Type: string | null
• Description: The primary contact person at the business location.
• Required: No

basics.dbaEmail

• Type: string | null
• Description: The business email address.
• Required: No

basics.dbaPhone

• Type: string | null
• Description: The business phone number.
• Required: No

basics.dbaStreet1

• Type: string | null
• Description: The first line of the business address.
• Required: No

basics.dbaStreet2

• Type: string | null
• Description: The second line of the business address (suite, unit, etc).
• Required: No

basics.dbaCity

• Type: string | null
• Description: The city of the business address.
• Required: No

basics.dbaState

• Type: string | null
• Description: The state/province of the business address.
• Required: No

basics.dbaZip

• Type: string | null
• Description: The postal code of the business address.
• Required: No

basics.dbaTaxID

• Type: string | null
• Description: The tax identification number (EIN, SSN) of the business. This field is encrypted at rest and redacted in merchant-facing views.
• Required: No

basics.dbaStruct

• Type: string | null
• Description: The legal structure of the business (LLC, Corporation, Sole Proprietorship, etc).
• Required: No

basics.dbaTraded

• Type: string | null
• Description: Indicates if the business is publicly traded.
• Required: No

basics.locationDifferent

• Type: boolean | null
• Description: Indicates if the business location is different from the legal address.
• Required: No
• Default: false

basics.primaryLanguage

• Type: string | null
• Description: The primary language used by the business.
• Required: No
• Default: "English"

basics.tinType

• Type: string | null
• Description: The type of tax identification number provided (EIN, SSN).
• Required: No

Business Details

businessDetails.b2BSalesPercent

• Type: integer | null
• Description: Percentage of sales that are business-to-business.
• Required: No

businessDetails.publicSalesPercent

• Type: integer | null
• Description: Percentage of sales that are to the general public.
• Required: No

businessDetails.mccCategory

• Type: string | null
• Description: The Merchant Category Code category for the business.
• Required: No

businessDetails.mccNumber

• Type: string | null
• Description: The specific Merchant Category Code for the business.
• Required: No

businessDetails.website

• Type: string | null
• Description: The business website URL.
• Required: No

businessDetails.productsServicesSold

• Type: string | null
• Description: Description of the products or services offered by the business.
• Required: No

businessDetails.seasonalMerchantBool

• Type: boolean | null
• Description: Indicates if the business is seasonal.
• Required: No
• Default: false

businessDetails.industryType

• Type: string | null
• Description: The industry classification of the business.
• Required: No

Business History

businessHistory.yearsInBiz

• Type: integer | null
• Description: Number of years the business has been operating.
• Required: No

businessHistory.monthsInBiz

• Type: integer | null
• Description: Additional months the business has been operating beyond full years.
• Required: No

businessHistory.openDate

• Type: string | null
• Description: The date the business started operations.
• Required: No

businessHistory.previousCcProcessor

• Type: string | null
• Description: The previous credit card processor used by the business, if any.
• Required: No

businessHistory.creditAcceptHistoryBool

• Type: string | null
• Description: Indicates if the business has previously accepted credit cards.
• Required: No

businessHistory.bankruptcyBool

• Type: boolean | null
• Description: Indicates if the business has filed for bankruptcy.
• Required: No
• Default: false

businessHistory.cardAcceptTerminationBool

• Type: boolean | null
• Description: Indicates if the business has previously had card acceptance terminated.
• Required: No
• Default: false

businessHistory.chargebacksLastYear

• Type: integer | null
• Description: Number of chargebacks in the past year.
• Required: No
• Default: 0

businessHistory.chargebackTotalAmount

• Type: integer | null
• Description: Total amount of chargebacks in the past year (in cents).
• Required: No
• Default: 0

Business Banking

businessBanking.bankName

• Type: string | null
• Description: The name of the business’s bank.
• Required: No

businessBanking.bankContact

• Type: string | null
• Description: The contact person at the bank.
• Required: No

businessBanking.bankRouting

• Type: string | null
• Description: The bank’s routing number.
• Required: No

businessBanking.bankAccount

• Type: string | null
• Description: The business’s bank account number. This field is encrypted at rest and redacted in merchant-facing views.
• Required: No

Order Processing

orderProcessing.cardSwipePercent

• Type: integer | null
• Description: Percentage of transactions that are card-present (swiped).
• Required: No

orderProcessing.cardKeyedPercent

• Type: integer | null
• Description: Percentage of transactions that are manually keyed.
• Required: No

orderProcessing.cardMoToPercent

• Type: integer | null
• Description: Percentage of transactions that are mail order/telephone order.
• Required: No

orderProcessing.cardInternetPercent

• Type: integer | null
• Description: Percentage of transactions that are online/e-commerce.
• Required: No

orderProcessing.cardAcceptanceMethods

• Type: string | null
• Description: The methods used for accepting card payments.
• Required: No

orderProcessing.cardDescriptor

• Type: string | null
• Description: How the business name will appear on customers’ credit card statements.
• Required: No

orderProcessing.customerServicePhone

• Type: string | null
• Description: Customer service phone number for transaction inquiries.
• Required: No

orderProcessing.customerServiceEmail

• Type: string | null
• Description: Customer service email for transaction inquiries.
• Required: No

orderProcessing.refundPolicy

• Type: string | null
• Description: The business’s refund policy.
• Required: No

orderProcessing.serviceOnly

• Type: boolean | null
• Description: Indicates if the business only provides services (no physical products).
• Required: No
• Default: false

Schedule A Basics

scheduleABasics.avgCreditCardSales

• Type: integer | null
• Description: Average monthly credit card sales volume (in dollars).
• Required: No

scheduleABasics.avgSaleAmount

• Type: integer | null
• Description: Average transaction amount (in dollars).
• Required: No

scheduleABasics.maxSaleAmount

• Type: integer | null
• Description: Maximum expected transaction amount (in dollars).
• Required: No

scheduleABasics.highMonthlyVolume

• Type: integer | null
• Description: Highest expected monthly volume (in dollars).
• Required: No

System Information

system.appStatus

• Type: string
• Description: Current status of the application (“pending”, “submitted”, “in_review”, “approved”, “rejected”).
• Required: Yes
• Default: "pending"

system.submitted

• Type: boolean
• Description: Indicates if the application has been submitted for review.
• Required: Yes
• Default: false

system.submittedBy

• Type: string | null
• Description: Who submitted the application (“merchant” or user email).
• Required: No

system.submittedDate

• Type: string (ISO 8601 datetime) | null
• Description: When the application was submitted.
• Required: No

system.appKey

• Type: string
• Description: Unique key for merchant access to the application.
• Required: Auto-generated

Audit Log

auditLog

• Type: array of audit event objects
• Description: A comprehensive log of all significant events and actions performed on the application. Each event captures who performed the action, when it occurred, and relevant details.
• Required: Auto-generated
• Read-only: Yes

Each audit log entry contains:

• id: Unique identifier for the audit log entry
• event: The type of event (e.g., application_created, application_updated, application_sensitive_data_revealed)
• user: Email address or identifier of the user who performed the action
• apiKey: API key identifier if the action was performed via API key authentication (null for regular user sessions)
• data: Event-specific data containing details about what was changed or accessed
• created: Timestamp when the event occurred (ISO 8601 format)
• requestMethod: HTTP method used (GET, POST, PATCH, DELETE)
• requestPath: API endpoint path that was called
• requestHeaders: Sanitized HTTP headers from the request (sensitive values like authorization are masked)
• requestIpAddress: IP address of the request origin
• account_id: Account ID associated with the action

Common Audit Events

application_created

• Triggered when a new application is created
• Captures the initial application data and who created it

application_updated

• Triggered when application data is modified
• Contains details of fields that were changed

application_sensitive_data_revealed

• Triggered when sensitive data is explicitly accessed via the reveal endpoint
• Critical for compliance and security auditing
• For API key access, requires x-user-to-log-for-request header for user identification
• Event data includes:
  • user: The identifier of who accessed the data (email or value from x-user-to-log-for-request)
  • applicationId: The application whose data was accessed
  • timestamp: When the access occurred
  • fields: Array of fields that were revealed, including:
    • field: The field name (e.g., “socialSecurityNumber”, “dbaTaxID”)
    • ownerId: For owner-specific fields, the database ID of the owner
    • ownerUniqueId: For owner-specific fields, the unique identifier of the owner
    • ownerEmail: For owner-specific fields, the owner’s email address
    • ownerName: For owner-specific fields, the full name of the owner

application_submitted

• Triggered when an application is submitted for review
• Captures who submitted it (merchant or internal user)

Example audit log entry for sensitive data access:

{
  "id": 1752,
  "event": "application_sensitive_data_revealed",
  "data": {
    "user": "compliance.user@company.com",
    "fields": [
      {
        "field": "dbaTaxID"
      },
      {
        "field": "socialSecurityNumber",
        "ownerId": 45,
        "ownerName": "John Doe",
        "ownerEmail": "john@example.com",
        "ownerUniqueId": "6112f756-6e38-4d43-85b2-77cf5308682b"
      }
    ],
    "timestamp": "2025-10-13T18:48:19.735Z",
    "applicationId": "8911760381296138"
  },
  "user": "compliance.user@company.com",
  "apiKey": "apiKey-2kpRPa2LQ3qbXGvOnkFRXo",
  "created": "2025-10-13T18:48:19.739Z",
  "requestMethod": "POST",
  "requestPath": "/api/applications/8911760381296138/reveal-sensitive-data",
  "requestHeaders": {
    "host": "api.pulsecrm.com",
    "x-api-key": "apiKey-2kpRPa2LQ3qbXGvOnkFRXo",
    "content-type": "application/json",
    "x-account-id": "2311",
    "x-user-to-log-for-request": "compliance.user@company.com"
  },
  "requestIpAddress": "192.168.1.100",
  "account_id": "2311"
}

Business Owners

Business owners are provided as an array of objects with the following properties:

businessOwners[].id

• Type: integer
• Description: The unique identifier for the business owner.
• Required: Auto-generated when created, required when updating

businessOwners[].firstName

• Type: string
• Description: The first name of the business owner.
• Required: Yes

businessOwners[].lastName

• Type: string
• Description: The last name of the business owner.
• Required: Yes

businessOwners[].titlePosition

• Type: string | null
• Description: The business owner’s title or position.
• Required: No

businessOwners[].emailAddress

• Type: string | null
• Description: The business owner’s email address.
• Required: No

businessOwners[].cellPhone

• Type: string | null
• Description: The business owner’s mobile phone number.
• Required: No

businessOwners[].equityOwnership

• Type: integer
• Description: The percentage of the business owned by this individual.
• Required: Yes

businessOwners[].controllingInterestBool

• Type: boolean
• Description: Indicates if the owner has controlling interest in the business.
• Required: Yes
• Default: false

businessOwners[].applicantBool

• Type: boolean
• Description: Indicates if the owner is also the applicant.
• Required: No
• Default: false

businessOwners[].socialSecurityNumber

• Type: string | null
• Description: The business owner’s social security number. This field is encrypted at rest and redacted in merchant-facing views.
• Required: No

businessOwners[].dateOfBirth

• Type: string | null
• Description: The business owner’s date of birth. This field is encrypted at rest and redacted in merchant-facing views.
• Required: No

Related Endpoints

The following endpoints are available for working with applications:

List Applications

GET /applications

Returns a paginated list of applications with support for filtering, sorting, and searching.

Create Application

POST /applications

Creates a new application with the provided data. Returns the created application with an appKey for merchant access.

Get Application by ID

GET /applications/{applicationId}

Retrieves a specific application by its ID.

Update Application

PATCH /applications/{applicationId}

Updates an existing application with new data.

Delete Application

DELETE /applications/{applicationId}

Permanently deletes an application from the system.

Submit Application

POST /applications/{applicationId}/submit

Submits an application for review, changing its status to “submitted” and locking it for merchant edits.

AI Analysis

POST /applications/{applicationId}/ai-analysis

Generates an AI-powered risk analysis for the application.

Reveal Sensitive Data

POST /applications/{applicationId}/reveal-sensitive-data

Explicitly reveals specific sensitive fields that are normally redacted. This endpoint requires the readApplicationSensitiveData permission and creates an audit log entry for compliance tracking.

Request Body:

[
  {
    "field": "dbaTaxID"
  },
  {
    "field": "socialSecurityNumber",
    "ownerEmail": "owner@example.com"
  }
]

Supported Fields:

• dbaTaxID: Business tax ID
• bankAccount: Bank account number
• socialSecurityNumber: Owner SSN (requires owner identifier)
• dateOfBirth: Owner date of birth (requires owner identifier)
• driversLicenseNumber: Owner driver’s license (requires owner identifier)
• driversLicenseExpiration: Owner DL expiration (requires owner identifier)
• passportNumber: Owner passport number (requires owner identifier)
• passportExpiration: Owner passport expiration (requires owner identifier)

Owner Identifiers:

For owner-specific fields, include one of:

• ownerId: Database ID of the owner
• ownerUniqueId: Unique identifier of the owner
• ownerEmail: Email address of the owner

API Key Authentication:

When using API keys to access this endpoint, you must provide user identification via:

• x-user-to-log-for-request header (recommended), OR
• userToLogForRequest field in each request object

The value must be at least 5 characters and should identify the end user accessing the data (e.g., email, user ID, or name).

Response:

{
  "success": true,
  "applicationId": "app_123",
  "data": [
    {
      "field": "dbaTaxID",
      "value": "12-3456789"
    },
    {
      "field": "socialSecurityNumber",
      "value": "123-45-6789",
      "ownerId": 45,
      "ownerUniqueId": "uuid-here",
      "ownerEmail": "owner@example.com",
      "ownerName": "John Doe"
    }
  ]
}

Audit Logging:

Every call to this endpoint creates an application_sensitive_data_revealed audit log entry that includes:

• Who accessed the data (user email or API key user identifier)
• Which fields were revealed
• For owner fields: which specific owner’s data was accessed
• Timestamp of the access
• API key used (if applicable)

Sensitive Data Handling

Several fields in the application contain sensitive information that requires special handling:

• basics.dbaTaxID: Business tax ID (EIN)
• businessBanking.bankAccount: Bank account number
• businessOwners[].socialSecurityNumber: Owner SSN
• businessOwners[].dateOfBirth: Owner date of birth
• businessOwners[].driversLicenseNumber: Owner driver’s license
• businessOwners[].driversLicenseExpiration: Owner DL expiration
• businessOwners[].passportNumber: Owner passport number
• businessOwners[].passportExpiration: Owner passport expiration

Data Protection

These fields are:

• Encrypted at rest in the database using AES-256-GCM encryption
• Redacted with the string "REDACTED" when retrieved through standard GET endpoints
• Preserved when updating - any field containing "REDACTED" will maintain its existing encrypted value

Accessing Sensitive Data

To access the actual values of sensitive fields, use the dedicated reveal endpoint:

POST /applications/{applicationId}/reveal-sensitive-data

This endpoint:

• Requires the readApplicationSensitiveData permission
• Creates an audit log entry for every access
• Supports selective field revelation (request only what you need)
• For API key access, requires user identification via x-user-to-log-for-request header

Compliance & Auditing

All access to sensitive data is logged in the application’s auditLog with:

• Who accessed the data (user email or API key identifier)
• When the access occurred
• What fields were accessed
• Which specific owner’s data was accessed (for owner-specific fields)

This comprehensive audit trail ensures compliance with data protection regulations and provides visibility into who has viewed sensitive information.

Application Workflow States

Applications progress through a series of states tracked in the system.appStatus field:

1. pending: Initial state, can be edited by merchants and API users
2. submitted: Merchant has completed the application, locked for merchant edits
3. in_review: Application is being reviewed by underwriting
4. approved: Application has been approved for processing
5. rejected: Application has been rejected

Best Practices

• Always check the application status before making updates
• Use the appKey for merchant-facing interfaces, not the API authentication tokens
• When displaying applications to merchants, ensure sensitive fields are redacted
• Submit applications only when all required information is complete
• Track application status changes to maintain a proper workflow