Not logged in
Log In Now
Documentation > REST API > Customers
SwervePay REST API v2.0 - Customers
Return to REST API Index

This resource provides access to query, create, or modify customer records.

Base Resource: Customers
https://api.swervepay.com/v/2.0/{accountSid}/customers
Description
The base customers resource is used to query or create customer records. Sub-resources are available to manage customer payment options (tokens), to access transaction data, or run new transactions.
Supported Request Method(s)
GET, POST
Sub-resources
GET (Customers) - Query Customers
This is a resource for querying customers. The response will include a customerList of individual customer records.
Request Parameters
Parameter Max Length Description
accountRefId 256 Account Number from the calling system
afterId 12 Include results with customerId greater than this value
beforeId 12 Include results with customerId less than this value
count 4 The number of results to return (default 10, max 1000)
customerEmail 255 Email
customerFirstName 255 First Name
customerId 12 Customer unique identifier
customerLastName 255 Last Name
customerPhoneNumber 14 Mobile Number
customerRefId 256 Customer Reference Id from the calling system
maxId 12 Include results with customerId less than or equal to this value
minId 12 Include results with customerId greater or equal to this value
name 255 First and/or last name
sort 15 Response list sort order

Valid Values: "customerId_asc", "customerId_desc", "name_asc"

customerId_asc: (Default) Sort by customerId in ascending order
customerId_desc: Sort by customerId in descending order
name_asc: Results sorted by customerLastName, customerFirstName.
systemCustomerRefId 256 System Customer Reference Id from the calling system
Response Parameters: customerList of customer records
Parameter Max Length Description
accountRefId 256 Account Number from the calling system
customerAddress1 255 Address Line 1
customerAddress2 255 Address Line 2
customerCity 255 City
customerCompany 255 Company
customerEmail 255 Email
customerFaxNumber 14 Fax Number
customerFirstName 32 First Name
customerId 12 Customer unique identifier
customerLastName 50 Last Name
customerPhoneNumber 14 Mobile Number
customerRefId 256 Customer Reference Id from the calling system
customerSecondaryNumber 14 Secondary Number
customerState 2 2-letter state abbreviation
customerZip 10 ZIP code
systemCustomerRefId 256 System Customer Reference Id from the calling system
Example: Query Customers
JSON
XML
curl -XGET "https://api.swervepay.com/v/2.0/098f6bcd4621d373cade4e832627b4f6/customers?minId=200000026176&count=3" \
-H "Accept: application/json" \
-u "myusername:221b368d7f5f597867f525971f28ff75"
{
   "customerList" : [
      {
         "accountRefId" : "5678",
         "customerAddress1" : "1053 Gerald L. Bates Drive",
         "customerAddress2" : "Apartment 3B",
         "customerCity" : "Boston",
         "customerCompany" : "Clemens Markets",
         "customerEmail" : "EricPScott@teleworm.us",
         "customerFaxNumber" : null,
         "customerFirstName" : "Eric",
         "customerId" : "200000026176",
         "customerLastName" : "Scott",
         "customerPhoneNumber" : "(617) 631-7886",
         "customerRefId" : "9012",
         "customerSecondaryNumber" : "(617) 682-5782",
         "customerState" : "MA",
         "customerZip" : "02107",
         "systemCustomerRefId" : "1234"
      },
      {
         "accountRefId" : null,
         "customerAddress1" : "2528 Wilson Street",
         "customerAddress2" : null,
         "customerCity" : "Encintas",
         "customerCompany" : "Garden Master",
         "customerEmail" : "RyanSAnderson@rhyta.com",
         "customerFaxNumber" : null,
         "customerFirstName" : "Ryan",
         "customerId" : "200000026177",
         "customerLastName" : "Anderson",
         "customerPhoneNumber" : "(809) 706-7073",
         "customerRefId" : "33333333333333333",
         "customerSecondaryNumber" : null,
         "customerState" : "CA",
         "customerZip" : "92024",
         "systemCustomerRefId" : "9999"
      },
      {
         "accountRefId" : null,
         "customerAddress1" : "2860 Bates Brothers Road",
         "customerAddress2" : null,
         "customerCity" : "Westerville",
         "customerCompany" : null,
         "customerEmail" : "RebeccaDSimmons@dayrep.com",
         "customerFaxNumber" : "(614) 220-1731",
         "customerFirstName" : "Rebecca",
         "customerId" : "200000026178",
         "customerLastName" : "Simmons",
         "customerPhoneNumber" : "(614) 384-2578",
         "customerRefId" : null,
         "customerSecondaryNumber" : "(614) 220-1730",
         "customerState" : "OH",
         "customerZip" : "43081",
         "systemCustomerRefId" : null
      }
   ],
   "metadata" : {
      "customerList" : {
         "idField" : "customerId",
         "maxId" : "200000026178",
         "minId" : "200000026176",
         "more" : 1,
         "recordCount" : 3,
         "sort" : "customerId_asc"
      }
   }
}
Return to resource (Customers)
Return to the top
POST (Customers) - Create Customer
This is a resource for creating a new customer record.
Request Parameters
Parameter Required Max Length Description
accountRefId 256 Account Number from the calling system
customerAddress1 255 Address Line 1
customerAddress2 255 Address Line 2
customerCity 255 City
customerCompany 255 Company
customerEmail 255 Email
customerFaxNumber 14 Fax Number
customerFirstName Required 255 First Name
customerLastName Required 255 Last Name
customerPhoneNumber 14 Mobile Number
customerRefId 256 Customer Reference Id from the calling system
customerSecondaryNumber 14 Secondary Number
customerState 2 2-letter state abbreviation
customerZip 10 ZIP code
systemCustomerRefId 256 System Customer Reference Id from the calling system
Response Parameters: customer record
Parameter Max Length Description
accountRefId 256 Account Number from the calling system
customerAddress1 255 Address Line 1
customerAddress2 255 Address Line 2
customerCity 255 City
customerCompany 255 Company
customerEmail 255 Email
customerFaxNumber 14 Fax Number
customerFirstName 32 First Name
customerId 12 Customer unique identifier
customerLastName 50 Last Name
customerPhoneNumber 14 Mobile Number
customerRefId 256 Customer Reference Id from the calling system
customerSecondaryNumber 14 Secondary Number
customerState 2 2-letter state abbreviation
customerZip 10 ZIP code
systemCustomerRefId 256 System Customer Reference Id from the calling system
Example: Create Customer
JSON
XML
curl -D - -XPOST "https://api.swervepay.com/v/2.0/098f6bcd4621d373cade4e832627b4f6/customers" \
-H "Accept: application/json" \
-u "myusername:221b368d7f5f597867f525971f28ff75" \
-d "customerFirstName=Vanessa" \
-d "customerLastName=Shepard" \
-d "customerCompany=Record Town" \
-d "customerPhoneNumber=(971) 236-3550" \
-d "customerSecondaryNumber=(971) 236-3592" \
-d "customerEmail=VanessaMShepard@rhyta.com" \
-d "customerAddress1=2223 Hope Street" \
-d "customerCity=Portland" \
-d "customerState=OR" \
-d "customerZip=97220" \
-d "systemCustomerRefId=1234" \
-d "accountRefId=5678" \
-d "customerRefId=9012"
{
   "customer" : {
      "accountRefId" : "5678",
      "customerAddress1" : "2223 Hope Street",
      "customerAddress2" : null,
      "customerCity" : "Portland",
      "customerCompany" : "Record Town",
      "customerEmail" : "VanessaMShepard@rhyta.com",
      "customerFaxNumber" : null,
      "customerFirstName" : "Vanessa",
      "customerId" : "200000026191",
      "customerLastName" : "Shepard",
      "customerPhoneNumber" : "(971) 236-3550",
      "customerRefId" : "9012",
      "customerSecondaryNumber" : "(971) 236-3592",
      "customerState" : "OR",
      "customerZip" : "97220",
      "systemCustomerRefId" : "1234"
   },
   "metadata" : {}
}
Return to resource (Customers)
Return to the top
Sub-resource: Customer Details
https://api.swervepay.com/v/2.0/{accountSid}/customers/{customerId}
Return to base resource (Customers)
Description
This resource provides access to query or modify a specific customer record.
Supported Request Method(s)
GET, PUT
GET (Customer Details) - Query Customer Details
This is a resource for querying customer details. No request parameters are supported, the response is dictated by the {customerId} provided in the request URL.
Response Parameters: customer record
Parameter Max Length Description
accountRefId 256 Account Number from the calling system
customerAddress1 255 Address Line 1
customerAddress2 255 Address Line 2
customerCity 255 City
customerCompany 255 Company
customerEmail 255 Email
customerFaxNumber 14 Fax Number
customerFirstName 32 First Name
customerId 12 Customer unique identifier
customerLastName 50 Last Name
customerPhoneNumber 14 Mobile Number
customerRefId 256 Customer Reference Id from the calling system
customerSecondaryNumber 14 Secondary Number
customerState 2 2-letter state abbreviation
customerZip 10 ZIP code
systemCustomerRefId 256 System Customer Reference Id from the calling system
Example: Query Customer Detail
JSON
XML
curl -D - -XGET "https://api.swervepay.com/v/2.0/098f6bcd4621d373cade4e832627b4f6/customers/200000026191" \
-H "Accept: application/json" \
-u "myusername:221b368d7f5f597867f525971f28ff75"
{
   "customer" : {
      "accountRefId" : "5678",
      "customerAddress1" : "2223 Hope Street",
      "customerAddress2" : null,
      "customerCity" : "Portland",
      "customerCompany" : "Record Town",
      "customerEmail" : "VanessaMShepard@rhyta.com",
      "customerFaxNumber" : null,
      "customerFirstName" : "Vanessa",
      "customerId" : "200000026191",
      "customerLastName" : "Shepard",
      "customerPhoneNumber" : "(971) 236-3550",
      "customerRefId" : "9012",
      "customerSecondaryNumber" : "(971) 236-3592",
      "customerState" : "OR",
      "customerZip" : "97220",
      "systemCustomerRefId" : "1234"
   },
   "metadata" : {}
}
Return to sub-resource (Customer Details)
Return to base resource (Customers)
Return to the top
PUT (Customer Details) - Update Customer
This is a resource for modifying an existing customer record. Please note that all conditional required fields are only required if sepecified (if these fields are not being modified they do not need to be included in the request).
Request Parameters
Parameter Required Max Length Description
accountRefId 256 Account Number from the calling system
customerAddress1 255 Address Line 1
customerAddress2 255 Address Line 2
customerCity 255 City
customerCompany 255 Company
customerEmail 255 Email
customerFaxNumber 14 Fax Number
customerFirstName Conditional 255 First Name
customerLastName Conditional 255 Last Name
customerPhoneNumber 14 Mobile Number
customerRefId 256 Customer Reference Id from the calling system
customerSecondaryNumber 14 Secondary Number
customerState 2 2-letter state abbreviation
customerZip 10 ZIP code
systemCustomerRefId 256 System Customer Reference Id from the calling system
Response Parameters: customer record
Parameter Max Length Description
accountRefId 256 Account Number from the calling system
customerAddress1 255 Address Line 1
customerAddress2 255 Address Line 2
customerCity 255 City
customerCompany 255 Company
customerEmail 255 Email
customerFaxNumber 14 Fax Number
customerFirstName 32 First Name
customerId 12 Customer unique identifier
customerLastName 50 Last Name
customerPhoneNumber 14 Mobile Number
customerRefId 256 Customer Reference Id from the calling system
customerSecondaryNumber 14 Secondary Number
customerState 2 2-letter state abbreviation
customerZip 10 ZIP code
systemCustomerRefId 256 System Customer Reference Id from the calling system
Example: Update Customer Detail
JSON
XML
curl -D - -XPUT "https://api.swervepay.com/v/2.0/098f6bcd4621d373cade4e832627b4f6/customers/200000026191" \
-H "Accept: application/json" \
-u "myusername:221b368d7f5f597867f525971f28ff75" \
-d "customerPhoneNumber=9175257899" \
-d "customerEmail=vshepard@recordtownllc.com"
{
   "customer" : {
      "accountRefId" : "5678",
      "customerAddress1" : "2223 Hope Street",
      "customerAddress2" : null,
      "customerCity" : "Portland",
      "customerCompany" : "Record Town",
      "customerEmail" : "vshepard@recordtownllc.com",
      "customerFaxNumber" : null,
      "customerFirstName" : "Vanessa",
      "customerId" : "200000026191",
      "customerLastName" : "Shepard",
      "customerPhoneNumber" : "(917) 525-7899",
      "customerRefId" : "9012",
      "customerSecondaryNumber" : "(971) 236-3592",
      "customerState" : "OR",
      "customerZip" : "97220",
      "systemCustomerRefId" : "1234"
   },
   "metadata" : {}
}
Return to sub-resource (Customer Details)
Return to base resource (Customers)
Return to the top
Sub-resource: Tokens
https://api.swervepay.com/v/2.0/{accountSid}/customers/{customerId}/tokens
Return to base resource (Customers)
Description
This resource provides access to query customer token records. Tokens are stored payment options the customer has used or validated in the past. These tokens are used in lieu of cardholder information when processing a new transaction. Token data is only usable for the customer detail record it is associated with.
Supported Request Method(s)
GET
GET (Tokens) - Query Customer Tokens
This is a resource for querying customer tokens. No request parameters are supported, this query will return a tokenList of details of all available Customer tokens ordered from most recently to least recently used (in other words, the first item in the tokenList will be the payment option most recently used in a payment from the customer).
Response Parameters: tokenList of token records
Parameter Max Length Description
accountNumber 19 Masked credit card account number or ACH bank account number
achAccountHolderType 8 ACH account holder type, if applicable

Valid Values: "personal", "business"
achAccountType 8 ACH account type, if applicable

Valid Values: "checking", "savings"
billAddress1 255 Address Line 1
billAddress2 255 Address Line 2
billCity 255 City
billCompany 255 Company
billEmail 255 Email
billFaxNumber 14 Fax Number
billFirstName 32 First Name
billLastName 50 Last Name
billPhoneNumber 14 Mobile Number
billSecondaryNumber 14 Secondary Number
billState 2 2-letter state abbreviation
billZip 10 ZIP code
cardExpirationDate 4 Credit card expiration date (MMYY), if applicable
issuer 5 Card issuer (e.g. AMEX, DC, DISC, JCB, MC, VISA) or non-credit card transaction source (e.g. ACH, CASH, CHECK)
routingNumber 9 ACH routing number, if applicable
tokenId 12 Token Id
Example: Query Tokens
JSON
XML
curl -D - -XGET "https://api.swervepay.com/v/2.0/098f6bcd4621d373cade4e832627b4f6/customers/200000027190/tokens" \
-H "Accept: application/json" \
-u "myusername:221b368d7f5f597867f525971f28ff75"
{
   "metadata" : {
      "tokenList" : {
         "idField" : "tokenId",
         "maxId" : "30211",
         "minId" : "30188",
         "more" : 0,
         "recordCount" : 2,
         "sort" : "latestTransactionId_desc"
      }
   },
   "tokenList" : [
      {
         "accountNumber" : "4716xxxxxxxx0331",
         "billAddress1" : "181 Woodbridge Lane",
         "billAddress2" : null,
         "billCity" : "Detroit",
         "billCompany" : null,
         "billEmail" : "PatriciaKSteele@rhyta.com",
         "billFaxNumber" : null,
         "billFirstName" : "Patricia",
         "billLastName" : "Steele",
         "billPhoneNumber" : "(313) 456-6415",
         "billSecondaryNumber" : null,
         "billState" : "MI",
         "billZip" : "48202",
         "cardExpirationDate" : "0418",
         "issuer" : "VISA",
         "latestTransactionId" : "100000034001",
         "routingNumber" : null,
         "timestamp" : "2013-12-06 22:35:13",
         "tokenId" : "30211"
      },
      {
         "accountNumber" : "6011xxxxxxxx2006",
         "billAddress1" : "181 Woodbridge Lane",
         "billAddress2" : null,
         "billCity" : "Detroit",
         "billCompany" : null,
         "billEmail" : "PatriciaKSteele@rhyta.com",
         "billFaxNumber" : null,
         "billFirstName" : "Patricia",
         "billLastName" : "Steele",
         "billPhoneNumber" : "(313) 456-6415",
         "billSecondaryNumber" : null,
         "billState" : "MI",
         "billZip" : "48202",
         "cardExpirationDate" : "1016",
         "issuer" : "DISC",
         "latestTransactionId" : "100000033972",
         "routingNumber" : null,
         "timestamp" : "2013-11-29 22:58:41",
         "tokenId" : "30188"
      }
   ]
}
Return to sub-resource (Tokens)
Return to base resource (Customers)
Return to the top
Sub-resource: Token Details
https://api.swervepay.com/v/2.0/{accountSid}/customers/{customerId}/tokens/{tokenId}
Return to base resource (Customers)
Description
This resource provides access to query or deactivate a customer token detail record. Once deactivated, tokens cannot be restored without collecting cardholder data from the customer again.

NOTE: A token record cannot be modified directly from this resource. In order to modify cardholder data you must provide the new cardholder information with the next transaction including the {customerId} and excluding the old {tokenId} which will effectively generate a new token for usage going forward.
Supported Request Method(s)
DELETE, GET
DELETE (Token Details) - Remove Customer Token
This is a resource for deactivating an existing customer token. No request parameters are supported, the record to be removed is determined by the {tokenId} provided in the request URL. No response parameters will be returned; a successful token deactivation will be denoted by an HTTP 200 status.
Example: Delete Token
JSON
XML
curl -D - -XDELETE "https://api.swervepay.com/v/2.0/098f6bcd4621d373cade4e832627b4f6/customers/200000026191/tokens/29369" \
-H "Accept: application/json" \
-u "myusername:221b368d7f5f597867f525971f28ff75"
{
   "metadata" : {}
}
Return to sub-resource (Token Details)
Return to base resource (Customers)
Return to the top
GET (Token Details) - Query Customer Token Details
This is a resource for querying customer token details. No request parameters are supported, this query will return the detailed information for a single Customer token.
Response Parameters: tokenList of token records
Parameter Max Length Description
accountNumber 19 Masked credit card account number or ACH bank account number
achAccountHolderType 8 ACH account holder type, if applicable

Valid Values: "personal", "business"
achAccountType 8 ACH account type, if applicable

Valid Values: "checking", "savings"
billAddress1 255 Address Line 1
billAddress2 255 Address Line 2
billCity 255 City
billCompany 255 Company
billEmail 255 Email
billFaxNumber 14 Fax Number
billFirstName 32 First Name
billLastName 50 Last Name
billPhoneNumber 14 Mobile Number
billSecondaryNumber 14 Secondary Number
billState 2 2-letter state abbreviation
billZip 10 ZIP code
cardExpirationDate 4 Credit card expiration date (MMYY), if applicable
issuer 5 Card issuer (e.g. AMEX, DC, DISC, JCB, MC, VISA) or non-credit card transaction source (e.g. ACH, CASH, CHECK)
routingNumber 9 ACH routing number, if applicable
tokenId 12 Token Id
Example: Query Token Detail
JSON
XML
curl -D - -XGET "https://api.swervepay.com/v/2.0/098f6bcd4621d373cade4e832627b4f6/customers/200000026191/tokens/29369" \
-H "Accept: application/json" \
-u "myusername:221b368d7f5f597867f525971f28ff75"
{
   "metadata" : {},
   "token" : {
      "accountNumber" : "4916xxxxxxxx4477",
      "billAddress1" : "2223 Hope Street",
      "billAddress2" : null,
      "billCity" : "Portland",
      "billCompany" : "Record Town",
      "billEmail" : "vshepard@recordtownllc.com",
      "billFaxNumber" : null,
      "billFirstName" : "Vanessa",
      "billLastName" : "Shepard",
      "billPhoneNumber" : "(917) 525-7899",
      "billSecondaryNumber" : "(971) 236-3592",
      "billState" : "OR",
      "billZip" : "97220",
      "cardExpirationDate" : "0718",
      "issuer" : "VISA",
      "routingNumber" : null,
      "tokenId" : "29369"
   }
}
Return to sub-resource (Token Details)
Return to base resource (Customers)
Return to the top
Sub-resource: Transactions
https://api.swervepay.com/v/2.0/{accountSid}/customers/{customerId}/transactions
Return to base resource (Customers)
Description
This resource provides the ability to query or run new transactions associated with a specific customerId record.
Supported Request Method(s)
GET, POST
GET (Transactions) - Query Customer Transactions
This is a resource for querying customer transactions. This sub-resource is identical to the associated transactions resource without the need to pass a customerId parameter. The customerId parameter passed to the transactions resource will automatically be pulled from the {customerId} provided in the request URL.

See: GET Transactions

NOTE: A {customerId} parameter with this request will be automatically overridden by the {customerId} provided in the request URL.
Return to sub-resource (Transactions)
Return to base resource (Customers)
Return to the top
POST (Transactions) - Process New Transaction
This is a resource for issuing a new transactions. This sub-resource is identical to the associated transactions resource without the need to pass a customerId parameter. The customerId parameter passed to the transactions resource will automatically be pulled from the {customerId} provided in the request URL.

See: POST Transactions

NOTE: A {customerId} parameter with this request will be automatically overridden by the {customerId} provided in the request URL.
Return to sub-resource (Transactions)
Return to base resource (Customers)
Return to the top
© SwervePay LLC. All Rights Reserved.