Bulk Upload (Excel)

Transfer Center supports two bulk Excel flows. Both use the same five-step pipeline; only the template, storage path, keyType, and final bulkAdd endpoint differ.

Flow	Use when	Final outcome
Funding source links (contacts)	You want to create contacts and email/SMS them a link to enter bank details	Contacts created → links sent → funding sources created after the contact completes the link
Direct funding sources	You already have (or will supply) full bank details in the sheet	Funding sources created directly (contact matched by GID or created from row data)

Shared pipeline (both flows)

Authentication: Steps 1, 3, 4, and 5 require x-api-key. Step 3’s S3 PUT must not include Swirepay headers.

Important — two different fileUrl shapes:

Step	fileUrl value
Register upload (step 4)	Full HTTPS S3 URL (same URL you used for PUT)
bulkAdd (step 5)	Relative path from register response (entity.fileUrl), e.g. bulk_contact/account-…/uuid

---

Flow A: Funding source links (contacts)

Endpoints: GET /v1/funding-source-link/template → storage /v1/storage/upload/bulk-contact → POST /v1/funding-source-link/bulkAdd

Step 1 — Download template

curl --location 'https://api.swirepay.com/v1/funding-source-link/template' \
  --header 'x-api-key: YOUR_API_KEY'

Example response:

{
  "message": "OK",
  "entity": {
    "fileUrl": "https://s3.ap-south-1.amazonaws.com/swirepay-bulk-contact-stag/SP_contacts_template.xlsx"
  },
  "responseCode": 200,
  "status": "SUCCESS"
}

Download the file from entity.fileUrl. A reference copy is also available at /templates/SP_contacts_template.xlsx.

Step 2 — Fill the template

Column	Purpose
Name	Contact name
Email	Contact email
Phone number (include country code with '+')	Contact phone
Any Reference ID	Optional merchant reference
Contact Type	e.g. VENDOR, EMPLOYEE, CUSTOMER
Contact Type (if others)	Custom type when Contact Type is OTHER
Country Code	Address country (e.g. US)
Street, City, State, Postal Code	Address
Notification via	ALL, EMAIL, or SMS for the funding source link
[Add Extra Columns if required]	Marker column — see Meta columns

Validate data before upload. Incorrect rows may fail validation during processing.

Step 3 — Get pre-signed URL and upload to S3

curl --location 'https://api.swirepay.com/v1/storage/upload/bulk-contact' \
  --header 'x-api-key: YOUR_API_KEY'

Use the entity string from the response as the upload URL:

curl --location --request PUT 'PRESIGNED_URL_FROM_STEP_3' \
  --header 'Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' \
  --data-binary '@SP_contacts_template.xlsx'

Do not send x-api-key on the S3 PUT.

Step 4 — Register the uploaded file

curl --location 'https://api.swirepay.com/v1/storage/upload/bulk-contact' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "fileUrl": "FULL_HTTPS_S3_URL_FROM_STEP_3",
    "keyType": "BULK_CONTACT"
  }'

Save entity.fileUrl from the response (relative path).

API reference: Register Bulk Contact Upload

Step 5 — Process with bulkAdd

curl --location 'https://api.swirepay.com/v1/funding-source-link/bulkAdd' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "fileUrl": "bulk_contact/account-2c8d4ba2adb5445281e5ed8bc9ac73e2/8b8a2987-d882-42c1-9d62-2a0ed71896fb"
  }'

API reference: Bulk Funding Source Link from File

---

Flow B: Direct funding sources

Endpoints: GET /v1/funding-source/template → storage /v1/storage/upload/funding-source → POST /v1/funding-source/bulkAdd

Step 1 — Download template

curl --location 'https://api.swirepay.com/v1/funding-source/template' \
  --header 'x-api-key: YOUR_API_KEY'

Reference copy: /templates/SP_fundingsource_template.xlsx

Step 2 — Fill the template

Column	Purpose
Name, Email, Phone number, Any Reference ID	Contact fields (when creating contact on the fly)
Contact Gid	Existing contact — use either this or contact detail columns
Contact Type, Contact Type (if others)	Required when creating contact from row
Country Code, Street, City, State, Postal Code	Address when creating contact
Account Number, Account Holder Name, Routing Number	Issuer bank
Account Type	CHECKING, SAVINGS, or CURRENT
Business Type	INDIVIDUAL or BUSINESS
Bank Name	Issuer bank name
[Add Extra Columns if required]	Marker column — see below

Contact rule: Each row must include Contact Gid or enough contact columns to create the contact (name, email, phone, address, etc.).

Steps 3–5

Same as Flow A, but use:

• GET / POST /v1/storage/upload/funding-source
• "keyType": "BULK_FUNDING_SOURCE" in step 4
• POST /v1/funding-source/bulkAdd in step 5

API references:

• Get Pre-signed S3 URL for Bulk Funding Source Upload
• Register Bulk Funding Source Upload
• Bulk Add Funding Sources from File

---

Meta columns (both templates)

The last standard column is [Add Extra Columns if required].

• Add columns to the right of this header to attach custom meta key-value pairs on created resources (header = key, cell = value).
• If you do not need meta, delete this column and any extra columns so the backend does not create an empty meta object.

---

JSON bulk (not Excel)

To send funding source links for existing contacts without a file, use Bulk Add Funding Source Links (POST /v1/funding-source-link/multi-add). That API is separate from the Excel pipeline above.

---

After processing

Bulk jobs may run asynchronously. Poll contact or funding source APIs, or use Webhook Configurations for completion events.

Common pitfalls

• Using the relative fileUrl in step 4 (register expects the full S3 URL).
• Using the full S3 URL in step 5 (bulkAdd expects the relative path from step 4).
• Sending x-api-key on the S3 PUT.
• Missing Contact Gid and contact columns on the funding source template row.
• Leaving the meta marker column in the sheet when you do not want meta fields.

Related: Manage Contacts · Send Money to Contact