Person Entity object 人实体对象
An entity represents a person or organization possessing separate and distinct legal rights. You will create entities for each of your customers or users. An entity is required to create a bank account or a loan object. Read about entities in our data model section for more information.
一个实体代表一个人或组织,拥有独立和独特的法律权利。您将为每个客户或用户创建实体。创建银行账户或贷款对象需要实体。有关实体的更多信息,请阅读数据模型部分。
object parameters 对象参数
person_details 个人详细信息
object 反对
Contains all person details of the legal person entity. Only returned when entity type is PERSON
.
包含法人实体的所有个人详细信息。仅当实体类型为 PERSON
时才返回。
first_name 名
string 字符串
First name of the legal person. Must adhere to Fedwire character validation.
法人姓名。必须符合 Fedwire 字符验证。
last_name 姓氏
string 字符串
Last name of the legal person. Must adhere to Fedwire character validation.
法人姓氏。必须符合 Fedwire 字符验证。
middle_name 中间名
string 字符串
Middle name of the legal person. Must adhere to Fedwire character validation.
法人的中间名。必须符合 Fedwire 字符验证。
ssn
string 字符串
Social Security Number. SSN is required for U.S. citizens. ITIN may be shared in place of SSN.
社会安全号。美国公民必须提供 SSN。可使用 ITIN 代替 SSN。
passport 通关文牒
object 反对
Passport Details. Passport, Driver's License or National ID is required for non U.S. citizens.
护照详细信息。非美国公民需出示护照、驾照或身份证。
number 编号
string 字符串
Passport number 护照号码
country_code 国家代码
string 字符串
Country code where the passport was issued. US Passports will be rejected as we require US citizens to submit SSN.
护照签发地的国家代码。美国护照将被拒签,因为我们要求美国公民提交 SSN。
drivers_license 驾驶执照
object 反对
Driver's License Details. Passport, Driver's License or National ID is required for non U.S. citizens.
驾驶执照详细信息。非美国公民需出示护照、驾驶执照或国民身份证。
number 编号
string 字符串
Driver's license number 驾驶执照号码
country_code 国家代码
string 字符串
Country code where the driver's license was issued. ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
). US Drivers License will be rejected as we require US citizens to submit SSN.
驾照签发地的国家代码。ISO 3166-1 Alpha-2 国家代码(如 US, FR, UK, DE, ...
)。美国驾照将被拒绝,因为我们要求美国公民提交 SSN。
national_id
object 反对
National ID Details. Passport, Driver's License or National ID is required for non U.S. citizens.
国民身份证详情。非美国公民需出示护照、驾照或国民身份证件。
number 编号
string 字符串
National ID number 身份证号码
country_code 国家代码
string 字符串
Country code where the national ID was issued. ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
).
颁发国家身份证的国家代码。ISO 3166-1 Alpha-2 国家代码(如 US, FR, UK, DE, ...
)。
date_of_birth 出生日期
string 字符串
Date of birth (YYYY-MM-DD)
出生日期(年-月-日)
email 电子邮件
string 字符串
Email of the individual. Optional, but highly encouraged as it will increase likelihood of an automated verification.
个人电子邮件。可选项,但强烈建议使用,因为这将增加自动验证的可能性。
address 地址
object 反对
Addresses need to adhere to character validation, as addresses are used across multiple payment rails. Characters are validated according to the ACH Valid Character Specification.
地址需要遵守字符验证,因为地址会在多个支付系统中使用。字符根据 ACH 有效字符规范进行验证。
line_1 线_1
string 字符串
Address line 1 地址第 1 行
line_2 线_2
string 字符串
Address line 2 地址第 2 行
city 城市
string 字符串
City 城市
state 国
string 字符串
State name. For US addresses, this field is mandatory and only postal abbreviations (e.g. AL, CA, DE, ...
) are allowed.
州名。对于美国地址,该字段为必填字段,只允许使用邮政缩写(如 AL, CA, DE, ...
)。
postal_code 邮政编码
string 字符串
Postal code 邮政编码
country_code 国家代码
string 字符串
ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
).
ISO 3166-1 Alpha-2 国家代码(如 US, FR, UK, DE, ...
)。
documents 文件
array of objects 对象数组
List of documents which are uploaded with the Submit Document API
通过提交文件 API 上传的文件列表
id
string 字符串
Unique identifier for the object
对象的唯一标识符
is_root
boolean 布尔
Indicates if the entity is the root entity of the platform.
表示该实体是否是平台的根实体。
review_reasons 审查原因
array 矩阵
List of reasons the entity is in Manual_Review
该实体的原因清单 Manual_Review
type 类型
string 字符串
Type of entity. PERSON
for a person entity.
实体类型。 PERSON
为个人实体。
verification_status 验证状态
array 矩阵
Current status of the entity verification. Can be UNVERIFIED
, PENDING
,MANUAL_REVIEW
, VERIFIED
, or DENIED
实体验证的当前状态。可以是 UNVERIFIED
, PENDING
, MANUAL_REVIEW
, VERIFIED
, 或 DENIED
verification_tags 验证标签
string 字符串
A list of verification tags with more details about its identity verification process.
验证标记列表,包含身份验证过程的更多详细信息。
Person Entity object 人实体对象
{
"documents": [],
"id": "enti_2Q1ctiJm1NypVqCt8UBC8e4xTfH",
"is_root": false,
"person_details": {
"address": {
"city": "San Francisco",
"country_code": "US",
"line_1": "101 Market St",
"line_2": "Suite 1913",
"postal_code": "94105",
"state": "CA"
},
"date_of_birth": "1985-08-04",
"email": "oliver@column.com",
"first_name": "Oliver",
"last_name": "Hockey",
"middle_name": "Smith",
"passport": {},
"ssn": "565438976",
"drivers_license":null,
"national_id": null
},
"review_reasons": [],
"type": "PERSON",
"verification_status": "VERIFIED"
}
Business Entity object 业务实体对象
A business entity represents a legal business in the Column data model.
业务实体在列数据模型中代表一个合法业务。
object parameters 对象参数
business_details 业务详情
object 反对
Contains all business details of the legal business entity. Only returned when entity type is BUSINESS
.
包含合法企业实体的所有业务详细信息。仅当实体类型为 BUSINESS
时才返回。
address 地址
object 反对
Addresses need to adhere to character validation, as addresses are used across multiple payment rails. Characters are validated according to the ACH Valid Character Specification.
地址需要遵守字符验证,因为地址会在多个支付系统中使用。字符根据 ACH 有效字符规范进行验证。
line_1 线_1
string 字符串
Address line 1 地址第 1 行
line_2 线_2
string 字符串
Address line 2 地址第 2 行
city 城市
string 字符串
City 城市
state 国
string 字符串
State name. For US addresses, this field is mandatory and only postal abbreviations (e.g. AL, CA, DE, ...
) are allowed.
州名。对于美国地址,该字段为必填字段,只允许使用邮政缩写(如 AL, CA, DE, ...
)。
postal_code 邮政编码
string 字符串
Postal code 邮政编码
country_code 国家代码
string 字符串
ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
).
ISO 3166-1 Alpha-2 国家代码(如 US, FR, UK, DE, ...
)。
beneficial_owners 受益所有人
array of objects 对象数组
A list of all the persons who have ultimate control over funds in the business, whether through ownership or other means.
通过所有权或其他方式最终控制企业资金的所有人员名单。
This is anyone who owns owns 25 percent or more of the business and those who control the funds. If no one owns more than 25% of the business, just the individual who has ultimate control of the funds must be included.
这是指任何拥有企业 25% 或以上股份的人以及控制资金的人。如果没有人拥有企业 25% 以上的股份,则必须包括最终控制资金的个人。
first_name 名
string 字符串
First name of the legal person
法人姓名
last_name 姓氏
string 字符串
Last name of the legal person
法人姓氏
middle_name 中间名
string 字符串
Middle name of the legal person
法人中间名
ssn
string 字符串
Social Security Number is required for US beneficial owners. Passport, driver's license, or national ID is required for foreign beneficial owners.
美国受益所有人需提供社会安全号。外国受益所有人需要提供护照、驾照或身份证。
passport 通关文牒
object 反对
Passport Number. SSN, passport, driver's license, or national ID is required.
护照号码。需要 SSN、护照、驾照或身份证。
number 编号
string 字符串
Passport number 护照号码
country_code 国家代码
string 字符串
Country code where the passport was issued. US Passports will be rejected as we require US citizens to submit SSN.
护照签发地的国家代码。美国护照将被拒签,因为我们要求美国公民提交 SSN。
drivers_license 驾驶执照
object 反对
Driver's license. SSN, passport, driver's license, or national ID is required.
驾驶执照。需要 SSN、护照、驾照或国民身份证。
number 编号
string 字符串
Driver's license number 驾驶执照号码
country_code 国家代码
string 字符串
Country code where the driver's license was issued. ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
). US Drivers License will be rejected as we require US citizens to submit SSN.
驾照签发地的国家代码。ISO 3166-1 Alpha-2 国家代码(如 US, FR, UK, DE, ...
)。美国驾照将被拒绝,因为我们要求美国公民提交 SSN。
national_id
object 反对
National ID. SSN, passport, driver's license, or national ID is required.
国民身份证。需要 SSN、护照、驾照或国民身份证。
number 编号
string 字符串
National ID number 身份证号码
country_code 国家代码
string 字符串
Country code where the national ID was issued. ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
).
颁发国家身份证的国家代码。ISO 3166-1 Alpha-2 国家代码(如 US, FR, UK, DE, ...
)。
date_of_birth 出生日期
string 字符串
Date of birth (YYYY-MM-DD)
出生日期(年-月-日)
email 电子邮件
string 字符串
Email of the individual. Optional, but highly encouraged as it will increase likelihood of an automated verification.
个人电子邮件。可选项,但强烈建议使用,因为这将增加自动验证的可能性。
is_control_person
boolean 布尔
Boolean value which specifies if this person is a designated control person.
布尔值,指明此人是否为指定控制人员。
is_beneficial_owner
boolean 布尔
Boolean value which specifies if this person is a designated beneficial owner.
布尔值,指明此人是否为指定受益所有人。
ownership_percentage 所有权百分比
integer 整数
Percentage ownership, specified as a integer, of the beneficial owner
实益拥有人的所有权百分比(以整数表示
job_title 职位名称
string 字符串
Job title of the beneficial owner or control person.
实际所有人或控制人的职务。
address 地址
object 反对
Addresses need to adhere to character validation, as addresses are used across multiple payment rails. Characters are validated according to the ACH Valid Character Specification.
地址需要遵守字符验证,因为地址会在多个支付系统中使用。字符根据 ACH 有效字符规范进行验证。
line_1 线_1
string 字符串
Address line 1 地址第 1 行
line_2 线_2
string 字符串
Address line 2 地址第 2 行
city 城市
string 字符串
City 城市
state 国
string 字符串
State name. For US addresses, this field is mandatory and only postal abbreviations (e.g. AL, CA, DE, ...
) are allowed.
州名。对于美国地址,该字段为必填字段,只允许使用邮政缩写(如 AL, CA, DE, ...
)。
postal_code 邮政编码
string 字符串
Postal code 邮政编码
country_code 国家代码
string 字符串
ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
).
ISO 3166-1 Alpha-2 国家代码(如 US, FR, UK, DE, ...
)。
business_name 企业名称
string 字符串
Legal Business Name 合法企业名称
ein
string 字符串
Employer Identification Number (Tax ID). This may be SSN for a sole proprietorship.
雇主识别号(税号)。独资企业可以使用 SSN。
registration_id 注册编号
object 反对
Registration ID. EIN or Registration ID is required.
注册 ID。需要提供 EIN 或注册 ID。
number 编号
string 字符串
Business registration ID 商业登记 ID
country_code 国家代码
string 字符串
Country code where the business registration ID was issued. ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
).
颁发企业注册 ID 的国家代码。ISO 3166-1 Alpha-2 国家代码(如 US, FR, UK, DE, ...
)。
industry 产业
string 字符串
Industry in which the business entity operates.
企业实体所处的行业。
website 网站
string 字符串
Website of the business. Optional, but highly encouraged as it will increase likelihood of an automated verification.
企业网站。可选项,但强烈建议使用,因为这将增加自动验证的可能性。
legal_type 法律类型
string 字符串
Type of business. Permitted values are limited-partnership
, trust
, sole-proprietorship
, corporation
,llc
, general-partnership
, professional-association
,government
,non-profit
, other
.
业务类型。允许的值为 limited-partnership
, trust
, sole-proprietorship
, corporation
, llc
, general-partnership
, professional-association
, government
, non-profit
, other
。
state_of_incorporation 公司注册地
string 字符串
State in which the business is incorporated. Only postal abbreviations (e.g. AL, CA, DE, ...) are allowed. Only required for a root entity.
企业注册地所在州。只允许使用邮政缩写(如 AL、CA、DE......)。只有根实体才需要。
year_of_incorporation 公司成立年份
string 字符串
Year in which the business entity was incorporated. Only required for a root entity.
企业实体成立的年份。仅根实体需要填写。
account_usage 账户使用情况
array of strings 字符串数组
Indicates possible uses of the accounts an entity may use at Column. Only required for a root entity.
表示实体在 Column 可能使用的账户。仅根实体需要。
description 描述
string 字符串
Description of the business entity. Only required for a root entity.
业务实体的描述。仅根实体需要。
payment_volumes 付款量
string 字符串
Expected payment volumes. Only required for a root entity.
预期付款量。仅根实体需要。
countries_of_operation 业务所在国
array of strings 字符串数组
Countries in which the business currently operates or expects to operate. Only ISO 3166-1 Alpha-2 Country Codes (e.g., US, FR, UK, DE, ...
) are allowed. Only required for a root entity.
企业目前运营或预期运营的国家。只允许使用 ISO 3166-1 Alpha-2 国家代码(如 US, FR, UK, DE, ...
)。只有根实体才需要。
is_root
boolean 布尔
Indicates if the entity is the root entity of the platform.
表示该实体是否是平台的根实体。
documents 文件
array of objects 对象数组
List of documents which are uploaded with the Submit Document API
通过提交文件 API 上传的文件列表
id
string 字符串
Unique identifier for the object
对象的唯一标识符
review_reasons 审查原因
array 矩阵
List of reasons the entity is in Manual_Review
该实体的原因清单 Manual_Review
type 类型
string 字符串
Type of entity. BUSINESS
for a business entity.
实体类型。 BUSINESS
为企业实体。
verification_status 验证状态
array 矩阵
Current status of the entity verification. Can be UNVERIFIED
, PENDING
,MANUAL_REVIEW
, VERIFIED
, or DENIED
实体验证的当前状态。可以是 UNVERIFIED
, PENDING
, MANUAL_REVIEW
, VERIFIED
, 或 DENIED
verification_tags 验证标签
string 字符串
A list of verification tags with more details about its identity verification process.
验证标记列表,包含身份验证过程的更多详细信息。
Entity object 实体对象
{
"business_details": {
"account_usage": "",
"address": {
"city": "San Francisco",
"country_code": "US",
"line_1": "1110 Gorgas Avenue",
"line_2": "Suite 1000",
"postal_code": "94109",
"state": "CA"
},
"beneficial_owners": [
{
"address": {
"city": "San Francisco",
"country_code": "US",
"line_1": "999 Bay Street",
"line_2": "",
"postal_code": "94109",
"state": "CA"
},
"date_of_birth": "1989-01-01",
"drivers_license": null,
"email": "mbakery@bakery.com",
"first_name": "Sam",
"last_name": "Smith",
"middle_name": "Test",
"national_id": null,
"passport": {},
"ssn": "999999999"
}
],
"business_name": "Maries Bakery",
"countries_of_operation": null,
"year_of_incorporation": "2022",
"description": "Bakery",
"ein": "111111111",
"industry": "",
"legal_type": "",
"payment_volumes": null,
"registration_id": {
"country_code": "US",
"number": "111111111"
},
"state_of_incorporation": "CA",
"website": "acme.com"
},
"documents": [],
"id": "enti_2dk2oXqPcB5Xb5wFpnrg50F7BeD",
"is_root": false,
"review_reasons": [],
"type": "BUSINESS",
"verification_status": "VERIFIED"
}
Create a legal person entity
创建法人实体
POST 职位
/entities/person /ities/person
Creates a legal person entity.
创建法人实体。
body parameters 机体参数
first_name 名
string 字符串
Required 需要
First name of the legal person. Must adhere to Fedwire character validation.
法人姓名。必须符合 Fedwire 字符验证。
last_name 姓氏
string 字符串
Required 需要
Last name of the legal person. Must adhere to Fedwire character validation.
法人姓氏。必须符合 Fedwire 字符验证。
middle_name 中间名
string 字符串
Optional 可选
Middle name of the legal person. Must adhere to Fedwire character validation.
法人的中间名。必须符合 Fedwire 字符验证。
ssn
string 字符串
Required 需要
Social Security Number. SSN is required for U.S. citizens. ITIN may be shared in place of SSN.
社会安全号。美国公民必须提供 SSN。可使用 ITIN 代替 SSN。
passport 通关文牒
object 反对
Optional 可选
Passport Details. Passport, Driver's License or National ID is required for non U.S. citizens.
护照详细信息。非美国公民需出示护照、驾照或身份证。
number 编号
string 字符串
Required 需要
Passport number 护照号码
country_code 国家代码
string 字符串
Required 需要
Country code where the passport was issued. US Passports will be rejected as we require US citizens to submit SSN.
护照签发地的国家代码。美国护照将被拒签,因为我们要求美国公民提交 SSN。
drivers_license 驾驶执照
object 反对
Optional 可选
Driver's License Details. Passport, Driver's License or National ID is required for non U.S. citizens.
驾驶执照详细信息。非美国公民需出示护照、驾驶执照或国民身份证。
number 编号
string 字符串
Required 需要
Driver's license number 驾驶执照号码
country_code 国家代码
string 字符串
Required 需要
Country code where the driver's license was issued. ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
). US Drivers License will be rejected as we require US citizens to submit SSN.
驾照签发地的国家代码。ISO 3166-1 Alpha-2 国家代码(如 US, FR, UK, DE, ...
)。美国驾照将被拒绝,因为我们要求美国公民提交 SSN。
national_id
object 反对
Optional 可选
National ID Details. Passport, Driver's License or National ID is required for non U.S. citizens.
国民身份证详情。非美国公民需出示护照、驾照或国民身份证件。
number 编号
string 字符串
Required 需要
National ID number 身份证号码
country_code 国家代码
string 字符串
Required 需要
Country code where the national ID was issued. ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
).
颁发国家身份证的国家代码。ISO 3166-1 Alpha-2 国家代码(如 US, FR, UK, DE, ...
)。
date_of_birth 出生日期
string 字符串
Required 需要
Date of birth (YYYY-MM-DD)
出生日期(年-月-日)
email 电子邮件
string 字符串
Optional 可选
Email of the individual. Optional, but highly encouraged as it will increase likelihood of an automated verification.
个人电子邮件。可选项,但强烈建议使用,因为这将增加自动验证的可能性。
address 地址
object 反对
Required 需要
Addresses need to adhere to character validation, as addresses are used across multiple payment rails. Characters are validated according to the ACH Valid Character Specification.
地址需要遵守字符验证,因为地址会在多个支付系统中使用。字符根据 ACH 有效字符规范进行验证。
line_1 线_1
string 字符串
Required 需要
Address line 1 地址第 1 行
line_2 线_2
string 字符串
Optional 可选
Address line 2 地址第 2 行
city 城市
string 字符串
Required 需要
City 城市
state 国
string 字符串
Optional 可选
State name. For US addresses, this field is mandatory and only postal abbreviations (e.g. AL, CA, DE, ...
) are allowed.
州名。对于美国地址,该字段为必填字段,只允许使用邮政缩写(如 AL, CA, DE, ...
)。
postal_code 邮政编码
string 字符串
Optional 可选
Postal code 邮政编码
country_code 国家代码
string 字符串
Required 需要
ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
).
ISO 3166-1 Alpha-2 国家代码(如 US, FR, UK, DE, ...
)。
Request 要求
curl `https://api.column.com/entities/person` \
-XPOST \
-u :<YOUR API KEY> \
-d first_name=Oliver \
-d last_name=Hockey \
-d middle_name=Smith \
-d ssn=565438976 \
-d date_of_birth="1985-08-04" \
-d email="oliver@column.com" \
-d "address[line_1]"="101 Market St" \
-d "address[line_2]"="Suite 1913" \
-d "address[city]"="San Francisco" \
-d "address[state]"="CA" \
-d "address[postal_code]"="94105" \
-d "address[country_code]"="USA"
Response 回应
{
"documents": [],
"id": "enti_2Q1ctiJm1NypVqCt8UBC8e4xTfH",
"is_root": false,
"person_details": {
"address": {
"city": "San Francisco",
"country_code": "US",
"line_1": "101 Market St",
"line_2": "Suite 1913",
"postal_code": "94105",
"state": "CA"
},
"date_of_birth": "1985-08-04",
"email": "oliver@column.com",
"first_name": "Oliver",
"last_name": "Hockey",
"middle_name": "Smith",
"passport": {},
"ssn": "565438976",
"drivers_license": null,
"national_id": null
},
"review_reasons": [],
"type": "PERSON",
"verification_status": "VERIFIED"
}
Update a legal person entity
更新法人实体
PATCH 补丁
/entities/person/<entity_id>
/ities/person/<entity_id>
Update the information stored for a legal person. Do not use this to change the underlying legal person - only use this if the actual personal information changes (e.g. legal name changes, etc.).
更新法人的存储信息。请勿使用此功能更改基本法人--只有在实际个人信息发生变化(如法定姓名变更等)时才使用此功能。
path parameters 路径参数
entity_id
string 字符串
Required 需要
ID of the person entity you're updating
您要更新的个人实体的 ID
body parameters 机体参数
first_name 名
string 字符串
Required 需要
First name of the legal person. Must adhere to Fedwire character validation.
法人姓名。必须符合 Fedwire 字符验证。
last_name 姓氏
string 字符串
Required 需要
Last name of the legal person. Must adhere to Fedwire character validation.
法人姓氏。必须符合 Fedwire 字符验证。
middle_name 中间名
string 字符串
Optional 可选
Middle name of the legal person. Must adhere to Fedwire character validation.
法人的中间名。必须符合 Fedwire 字符验证。
ssn
string 字符串
Required 需要
Social Security Number. SSN is required for U.S. citizens. ITIN may be shared in place of SSN.
社会安全号。美国公民必须提供 SSN。可使用 ITIN 代替 SSN。
passport 通关文牒
object 反对
Optional 可选
Passport Details. Passport, Driver's License or National ID is required for non U.S. citizens.
护照详细信息。非美国公民需出示护照、驾照或身份证。
number 编号
string 字符串
Required 需要
Passport number 护照号码
country_code 国家代码
string 字符串
Required 需要
Country code where the passport was issued. US Passports will be rejected as we require US citizens to submit SSN.
护照签发地的国家代码。美国护照将被拒签,因为我们要求美国公民提交 SSN。
drivers_license 驾驶执照
object 反对
Optional 可选
Driver's License Details. Passport, Driver's License or National ID is required for non U.S. citizens.
驾驶执照详细信息。非美国公民需出示护照、驾驶执照或国民身份证。
number 编号
string 字符串
Required 需要
Driver's license number 驾驶执照号码
country_code 国家代码
string 字符串
Required 需要
Country code where the driver's license was issued. ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
). US Drivers License will be rejected as we require US citizens to submit SSN.
驾照签发地的国家代码。ISO 3166-1 Alpha-2 国家代码(如 US, FR, UK, DE, ...
)。美国驾照将被拒绝,因为我们要求美国公民提交 SSN。
national_id
object 反对
Optional 可选
National ID Details. Passport, Driver's License or National ID is required for non U.S. citizens.
国民身份证详情。非美国公民需出示护照、驾照或国民身份证件。
number 编号
string 字符串
Required 需要
National ID number 身份证号码
country_code 国家代码
string 字符串
Required 需要
Country code where the national ID was issued. ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
).
颁发国家身份证的国家代码。ISO 3166-1 Alpha-2 国家代码(如 US, FR, UK, DE, ...
)。
date_of_birth 出生日期
string 字符串
Required 需要
Date of birth (YYYY-MM-DD)
出生日期(年-月-日)
email 电子邮件
string 字符串
Optional 可选
Email of the individual. Optional, but highly encouraged as it will increase likelihood of an automated verification.
个人电子邮件。可选项,但强烈建议使用,因为这将增加自动验证的可能性。
address 地址
object 反对
Required 需要
Addresses need to adhere to character validation, as addresses are used across multiple payment rails. Characters are validated according to the ACH Valid Character Specification.
地址需要遵守字符验证,因为地址会在多个支付系统中使用。字符根据 ACH 有效字符规范进行验证。
line_1 线_1
string 字符串
Required 需要
Address line 1 地址第 1 行
line_2 线_2
string 字符串
Optional 可选
Address line 2 地址第 2 行
city 城市
string 字符串
Required 需要
City 城市
state 国
string 字符串
Optional 可选
State name. For US addresses, this field is mandatory and only postal abbreviations (e.g. AL, CA, DE, ...
) are allowed.
州名。对于美国地址,该字段为必填字段,只允许使用邮政缩写(如 AL, CA, DE, ...
)。
postal_code 邮政编码
string 字符串
Optional 可选
Postal code 邮政编码
country_code 国家代码
string 字符串
Required 需要
ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
).
ISO 3166-1 Alpha-2 国家代码(如 US, FR, UK, DE, ...
)。
Request 要求
curl https://api.column.com/entities/person/<entity_id> \
-XPATCH \
-u :<YOUR API KEY> \
-d first_name=Bruce \
-d last_name=Hockey \
-d middle_name=Smith \
-d ssn=565438976 \
-d date_of_birth="1985-08-04" \
-d email="apis@column.com" \
-d "address[line_1]"="101 Market St" \
-d "address[line_2]"="Suite 1913" \
-d "address[city]"="San Francisco" \
-d "address[state]"="CA" \
-d "address[postal_code]"="94105" \
-d "address[country_code]"="USA"
Response 回应
{
"documents": [],
"id": "enti_2Q1ctiJm1NypVqCt8UBC8e4xTfH",
"is_root": false,
"person_details": {
"address": {
"city": "San Francisco",
"country_code": "US",
"line_1": "101 Market St",
"line_2": "Suite 1913",
"postal_code": "94105",
"state": "CA"
},
"date_of_birth": "1985-08-04",
"email": "apis@column.com",
"first_name": "Bruce",
"last_name": "Hockey",
"middle_name": "Smith",
"passport": {},
"ssn": "565438976",
"drivers_license": null,
"national_id": null
},
"review_reasons": [],
"type": "PERSON",
"verification_status": "VERIFIED"
}
Create a legal business entity
创建合法企业实体
POST 职位
/entities/business
Creates a legal business entity.
创建一个合法的商业实体。
body parameters 机体参数
ein
string 字符串
Required 需要
Employer Identification Number (Tax ID)
雇主识别号(税号)
registration_id 注册编号
object 反对
Optional 可选
Registration ID, typically for a non US incorporated company. EIN or Registration ID is required.
注册 ID,通常用于非美国注册公司。需要提供 EIN 或注册 ID。
number 编号
string 字符串
Required 需要
Business registration ID 商业登记 ID
country_code 国家代码
string 字符串
Required 需要
Country code where the business registration ID was issued. ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
).
颁发企业注册 ID 的国家代码。ISO 3166-1 Alpha-2 国家代码(如 US, FR, UK, DE, ...
)。
business_name 企业名称
string 字符串
Required 需要
Legal Business Name. Must adhere to Fedwire character validation.
合法企业名称。必须符合 Fedwire 字符验证。
website 网站
string 字符串
Optional 可选
Website of the business. Optional, but highly encouraged as it will increase likelihood of an automated verification.
企业网站。可选项,但强烈建议使用,因为这将增加自动验证的可能性。
legal_type 法律类型
string 字符串
Optional 可选
Type of business. Permitted values are limited-partnership
, trust
, sole-proprietorship
, corporation
,llc
, general-partnership
, professional-association
,government
,non-profit
, other
.
业务类型。允许的值为 limited-partnership
, trust
, sole-proprietorship
, corporation
, llc
, general-partnership
, professional-association
, government
, non-profit
, other
。
state_of_incorporation 公司注册地
string 字符串
Optional 可选
State in which the business is incorporated. Only postal abbreviations (e.g. AL, CA, DE, ...) are allowed. Only required for a root entity.
企业注册地所在州。只允许使用邮政缩写(如 AL、CA、DE......)。只有根实体才需要。
year_of_incorporation 公司成立年份
string 字符串
Optional 可选
Year in which the business entity was incorporated. Only required for a root entity.
企业实体成立的年份。仅根实体需要填写。
account_usage 账户使用情况
array of strings 字符串数组
Optional 可选
Indicates possible uses of the accounts an entity may use at Column. Only required for a root entity.
表示实体在 Column 可能使用的账户。仅根实体需要。
description 描述
string 字符串
Optional 可选
Description of the business entity. Only required for a root entity.
业务实体的描述。仅根实体需要。
payment_volumes 付款量
string 字符串
Optional 可选
Expected payment volumes. Only required for a root entity.
预期付款量。仅根实体需要。
countries_of_operation 业务所在国
array of strings 字符串数组
Optional 可选
Countries in which the business currently operates or expects to operate. Only ISO 3166-1 Alpha-2 Country Codes (e.g., US, FR, UK, DE, ...
) are allowed. Only required for a root entity.
企业目前运营或预期运营的国家。只允许使用 ISO 3166-1 Alpha-2 国家代码(如 US, FR, UK, DE, ...
)。只有根实体才需要。
address 地址
object 反对
Required 需要
Addresses need to adhere to character validation, as addresses are used across multiple payment rails. Characters are validated according to the ACH Valid Character Specification.
地址需要遵守字符验证,因为地址会在多个支付系统中使用。字符根据 ACH 有效字符规范进行验证。
line_1 线_1
string 字符串
Required 需要
Address line 1 地址第 1 行
line_2 线_2
string 字符串
Optional 可选
Address line 2 地址第 2 行
city 城市
string 字符串
Required 需要
City 城市
state 国
string 字符串
Optional 可选
State name. For US addresses, this field is mandatory and only postal abbreviations (e.g. AL, CA, DE, ...
) are allowed.
州名。对于美国地址,该字段为必填字段,只允许使用邮政缩写(如 AL, CA, DE, ...
)。
postal_code 邮政编码
string 字符串
Optional 可选
Postal code 邮政编码
country_code 国家代码
string 字符串
Required 需要
ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
).
ISO 3166-1 Alpha-2 国家代码(如 US, FR, UK, DE, ...
)。
beneficial_owners 受益所有人
array of objects 对象数组
Required 需要
A list of all the persons who have ultimate control over funds in the business, whether through ownership or other means.
通过所有权或其他方式最终控制企业资金的所有人员名单。
This is anyone who owns owns 25 percent or more of the business and those who control the funds. If no one owns more than 25% of the business, just the individual who has ultimate control of the funds must be included.
这是指任何拥有企业 25% 或以上股份的人以及控制资金的人。如果没有人拥有企业 25% 以上的股份,则必须包括最终控制资金的个人。
first_name 名
string 字符串
Required 需要
First name of the legal person
法人姓名
last_name 姓氏
string 字符串
Required 需要
Last name of the legal person
法人姓氏
middle_name 中间名
string 字符串
Optional 可选
Middle name of the legal person
法人中间名
ssn
string 字符串
Optional 可选
Social Security Number is required for US beneficial owners. Passport, driver's license, or national ID is required for foreign beneficial owners.
美国受益所有人需提供社会安全号。外国受益所有人需要提供护照、驾照或身份证。
passport 通关文牒
object 反对
Optional 可选
Passport Number. SSN, passport, driver's license, or national ID is required.
护照号码。需要 SSN、护照、驾照或身份证。
number 编号
string 字符串
Required 需要
Passport number 护照号码
country_code 国家代码
string 字符串
Required 需要
Country code where the passport was issued. US Passports will be rejected as we require US citizens to submit SSN.
护照签发地的国家代码。美国护照将被拒签,因为我们要求美国公民提交 SSN。
drivers_license 驾驶执照
object 反对
Optional 可选
Driver's license. SSN, passport, driver's license, or national ID is required.
驾驶执照。需要 SSN、护照、驾照或国民身份证。
number 编号
string 字符串
Required 需要
Driver's license number 驾驶执照号码
country_code 国家代码
string 字符串
Required 需要
Country code where the driver's license was issued. ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
). US Drivers License will be rejected as we require US citizens to submit SSN.
驾照签发地的国家代码。ISO 3166-1 Alpha-2 国家代码(如 US, FR, UK, DE, ...
)。美国驾照将被拒绝,因为我们要求美国公民提交 SSN。
national_id
object 反对
Optional 可选
National ID. SSN, passport, driver's license, or national ID is required.
国民身份证。需要 SSN、护照、驾照或国民身份证。
number 编号
string 字符串
Required 需要
National ID number 身份证号码
country_code 国家代码
string 字符串
Required 需要
Country code where the national ID was issued. ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
).
颁发国家身份证的国家代码。ISO 3166-1 Alpha-2 国家代码(如 US, FR, UK, DE, ...
)。
date_of_birth 出生日期
string 字符串
Required 需要
Date of birth (YYYY-MM-DD)
出生日期(年-月-日)
email 电子邮件
string 字符串
Optional 可选
Email of the individual. Optional, but highly encouraged as it will increase likelihood of an automated verification.
个人电子邮件。可选项,但强烈建议使用,因为这将增加自动验证的可能性。
is_control_person
boolean 布尔
Required 需要
Boolean value which specifies if this person is a designated control person.
布尔值,指明此人是否为指定控制人员。
is_beneficial_owner
boolean 布尔
Required 需要
Boolean value which specifies if this person is a designated beneficial owner.
布尔值,指明此人是否为指定受益所有人。
ownership_percentage 所有权百分比
integer 整数
Optional 可选
Percentage ownership, specified as a integer, of the beneficial owner
实益拥有人的所有权百分比(以整数表示
job_title 职位名称
string 字符串
Optional 可选
Job title of the beneficial owner or control person.
实际所有人或控制人的职务。
address 地址
object 反对
Required 需要
Addresses need to adhere to character validation, as addresses are used across multiple payment rails. Characters are validated according to the ACH Valid Character Specification.
地址需要遵守字符验证,因为地址会在多个支付系统中使用。字符根据 ACH 有效字符规范进行验证。
line_1 线_1
string 字符串
Required 需要
Address line 1 地址第 1 行
line_2 线_2
string 字符串
Optional 可选
Address line 2 地址第 2 行
city 城市
string 字符串
Required 需要
City 城市
state 国
string 字符串
Optional 可选
State name. For US addresses, this field is mandatory and only postal abbreviations (e.g. AL, CA, DE, ...
) are allowed.
州名。对于美国地址,该字段为必填字段,只允许使用邮政缩写(如 AL, CA, DE, ...
)。
postal_code 邮政编码
string 字符串
Optional 可选
Postal code 邮政编码
country_code 国家代码
string 字符串
Required 需要
ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
).
ISO 3166-1 Alpha-2 国家代码(如 US, FR, UK, DE, ...
)。
Request 要求
curl 'https://api.column.com/entities/business' \
-XPOST \
-u :<YOUR API KEY> \
-H 'Content-Type: application/json' \
-d '{
"ein": "999999999",
"business_name": "Maries Bakery",
"website": "mariesbakery.com",
"address": {
"line_1": "1110 Gorgas Avenue",
"line_2": "1000",
"city": "San Francisco",
"state": "CA",
"postal_code": "94109",
"country_code": "US"
},
"beneficial_owners": [
{
"date_of_birth": "1989-04-15",
"first_name": "Sam",
"middle_name": "Bruce",
"last_name": "Smith",
"ssn": "999999999",
"email": "samsmith@gmail.com",
"is_beneficial_owner": true,
"ownership_percentage": 50,
"address": {
"line_1": "999 Bay Street",
"city": "San Francisco",
"state": "CA",
"postal_code": "94109",
"country_code": "US"
}
}
]
}'
Response 回应
{
"business_details": {
"account_usage": "",
"address": {
"city": "San Francisco",
"country_code": "US",
"line_1": "1110 Gorgas Avenue",
"line_2": "1000",
"postal_code": "94109",
"state": "CA"
},
"beneficial_owners": [
{
"address": {
"city": "San Francisco",
"country_code": "US",
"line_1": "999 Bay Street",
"line_2": "",
"postal_code": "94109",
"state": "CA"
},
"date_of_birth": "1989-04-15",
"drivers_license": null,
"email": "samsmith@gmail.com",
"first_name": "Sam",
"is_beneficial_owner": true,
"is_control_person": false,
"job_title": "",
"last_name": "Smith",
"middle_name": "Bruce",
"national_id": null,
"ownership_percentage": 50,
"passport": {},
"ssn": "999999999"
}
],
"business_name": "Maries Bakery",
"countries_of_operation": null,
"description": null,
"ein": "999999999",
"industry": "",
"legal_type": "",
"payment_volumes": null,
"registration_id": {
"country_code": "US",
"number": "999999999"
},
"website": "mariesbakery.com"
},
"documents": [],
"id": "enti_2dskHOBMYaqdTGllzMJpLYt1lC5",
"is_root": false,
"review_reasons": [],
"type": "BUSINESS",
"verification_status": "VERIFIED"
}
Update a legal business entity
更新合法企业实体
PATCH 补丁
/entities/business/<entity_id>
This updates the information stored for this legal person. Changes to ssn, date of birth, and name will cause a re-verification process. Do not use this to change the underlying legal person - only use this if the actual personal information changes (e.g. legal name changes, etc.).
这将更新为该法人存储的信息。更改社保号、出生日期和姓名将导致重新验证过程。请勿使用此功能更改基本法人--只有在实际个人信息发生更改(如法定姓名更改等)时才使用此功能。
path parameters 路径参数
entity_id
string 字符串
Required 需要
ID of the business entity you're updating
您要更新的企业实体的 ID
body parameters 机体参数
business_name 企业名称
string 字符串
Optional 可选
Legal Business Name. Must adhere to Fedwire character validation.
合法企业名称。必须符合 Fedwire 字符验证。
industry 产业
string 字符串
Optional 可选
Industry in which the business entity operates.
企业实体所处的行业。
website 网站
string 字符串
Optional 可选
Website of the business. Optional, but highly encouraged as it will increase likelihood of an automated verification.
企业网站。可选项,但强烈建议使用,因为这将增加自动验证的可能性。
legal_type 法律类型
string 字符串
Optional 可选
Type of business. Permitted values are limited-partnership
, trust
, sole-proprietorship
, corporation
,llc
, general-partnership
, professional-association
,government
,non-profit
, other
.
业务类型。允许的值为 limited-partnership
, trust
, sole-proprietorship
, corporation
, llc
, general-partnership
, professional-association
, government
, non-profit
, other
。
state_of_incorporation 公司注册地
string 字符串
Optional 可选
State in which the business is incorporated. Only postal abbreviations (e.g. AL, CA, DE, ...) are allowed. Only required for a root entity.
企业注册地所在州。只允许使用邮政缩写(如 AL、CA、DE......)。只有根实体才需要。
year_of_incorporation 公司成立年份
string 字符串
Optional 可选
Year in which the business entity was incorporated. Only required for a root entity.
企业实体成立的年份。仅根实体需要填写。
account_usage 账户使用情况
array of strings 字符串数组
Optional 可选
Indicates possible uses of the accounts an entity may use at Column. Only required for a root entity.
表示实体在 Column 可能使用的账户。仅根实体需要。
description 描述
string 字符串
Optional 可选
Description of the business entity. Only required for a root entity.
业务实体的描述。仅根实体需要。
payment_volumes 付款量
string 字符串
Optional 可选
Expected payment volumes. Only required for a root entity.
预期付款量。仅根实体需要。
countries_of_operation 业务所在国
array of strings 字符串数组
Optional 可选
Countries in which the business currently operates or expects to operate. Only ISO 3166-1 Alpha-2 Country Codes (e.g., US, FR, UK, DE, ...
) are allowed. Only required for a root entity.
企业目前运营或预期运营的国家。只允许使用 ISO 3166-1 Alpha-2 国家代码(如 US, FR, UK, DE, ...
)。只有根实体才需要。
address 地址
object 反对
Optional 可选
line_1 线_1
string 字符串
Required 需要
Address line 1 地址第 1 行
line_2 线_2
string 字符串
Optional 可选
Address line 2 地址第 2 行
city 城市
string 字符串
Required 需要
City 城市
state 国
string 字符串
Optional 可选
State name. For US addresses, this field is mandatory and only postal abbreviations (e.g. AL, CA, DE, ...
) are allowed.
州名。对于美国地址,该字段为必填字段,只允许使用邮政缩写(如 AL, CA, DE, ...
)。
postal_code 邮政编码
string 字符串
Optional 可选
Postal code 邮政编码
country_code 国家代码
string 字符串
Required 需要
ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
).
ISO 3166-1 Alpha-2 国家代码(如 US, FR, UK, DE, ...
)。
beneficial_owners 受益所有人
array of objects 对象数组
Optional 可选
If beneficial owners are updated, the entire array of objects will be updated. This means you must pass the complete array of beneficial owners when updating.
如果更新受益所有人,则将更新整个对象数组。这意味着更新时必须传递受益所有人的完整数组。
A list of all the persons who have ultimate control over funds in the business, whether through ownership or other means.
通过所有权或其他方式最终控制企业资金的所有人员名单。
重试
错误原因
This is anyone who owns owns 25 percent or more of the business and those who control the funds. If no one owns more than 25% of the business, just the individual who has ultimate control of the funds must be included.
这是指任何拥有企业 25% 或以上股份的人以及控制资金的人。如果没有人拥有企业 25% 以上的股份,则必须包括最终控制资金的个人。
重试
错误原因
First name of the legal person
法人姓名
重试
错误原因
ssn
string 字符串
Optional 可选
Social Security Number is required for US beneficial owners. Passport, driver's license, or national ID is required for foreign beneficial owners.
美国受益所有人需提供社会安全号。外国受益所有人需要提供护照、驾照或身份证。
passport 通关文牒
object 反对
Optional 可选
Passport Number. SSN, passport, driver's license, or national ID is required.
护照号码。需要 SSN、护照、驾照或身份证。
number 编号
string 字符串
Required 需要
Passport number 护照号码
country_code 国家代码
string 字符串
Required 需要
Country code where the passport was issued. US Passports will be rejected as we require US citizens to submit SSN.
护照签发地的国家代码。美国护照将被拒签,因为我们要求美国公民提交 SSN。
drivers_license 驾驶执照
object 反对
Optional 可选
Driver's license. SSN, passport, driver's license, or national ID is required.
驾驶执照。需要 SSN、护照、驾照或国民身份证。
number 编号
string 字符串
Required 需要
Driver's license number 驾驶执照号码
country_code 国家代码
string 字符串
Required 需要
Country code where the driver's license was issued. ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
). US Drivers License will be rejected as we require US citizens to submit SSN.
驾照签发地的国家代码。ISO 3166-1 Alpha-2 国家代码(如 US, FR, UK, DE, ...
)。美国驾照将被拒绝,因为我们要求美国公民提交 SSN。
national_id
object 反对
Optional 可选
National ID. SSN, passport, driver's license, or national ID is required.
国民身份证。需要 SSN、护照、驾照或国民身份证。
number 编号
string 字符串
Required 需要
National ID number 身份证号码
country_code 国家代码
string 字符串
Required 需要
Country code where the national ID was issued. ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
).
颁发国家身份证的国家代码。ISO 3166-1 Alpha-2 国家代码(如 US, FR, UK, DE, ...
)。
date_of_birth 出生日期
string 字符串
Required 需要
Date of birth (YYYY-MM-DD)
出生日期(年-月-日)
email 电子邮件
string 字符串
Optional 可选
Email of the individual. Optional, but highly encouraged as it will increase likelihood of an automated verification.
个人电子邮件。可选项,但强烈建议使用,因为这将增加自动验证的可能性。
is_control_person
boolean 布尔
Required 需要
Boolean value which specifies if this person is a designated control person.
布尔值,指明此人是否为指定控制人员。
is_beneficial_owner
boolean 布尔
Required 需要
Boolean value which specifies if this person is a designated beneficial owner.
布尔值,指明此人是否为指定受益所有人。
ownership_percentage 所有权百分比
integer 整数
Optional 可选
Percentage ownership, specified as a integer, of the beneficial owner
实益拥有人的所有权百分比(以整数表示
job_title 职位名称
string 字符串
Optional 可选
Job title of the beneficial owner or control person.
实际所有人或控制人的职务。
address 地址
object 反对
Required 需要
Addresses need to adhere to character validation, as addresses are used across multiple payment rails. Characters are validated according to the ACH Valid Character Specification.
地址需要遵守字符验证,因为地址会在多个支付系统中使用。字符根据 ACH 有效字符规范进行验证。
line_1 线_1
string 字符串
Required 需要
Address line 1 地址第 1 行
line_2 线_2
string 字符串
Optional 可选
Address line 2 地址第 2 行
city 城市
string 字符串
Required 需要
City 城市
state 国
string 字符串
Optional 可选
State name. For US addresses, this field is mandatory and only postal abbreviations (e.g. AL, CA, DE, ...
) are allowed.
州名。对于美国地址,该字段为必填字段,只允许使用邮政缩写(如 AL, CA, DE, ...
)。
postal_code 邮政编码
string 字符串
Optional 可选
Postal code 邮政编码
country_code 国家代码
string 字符串
Required 需要
ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
).
ISO 3166-1 Alpha-2 国家代码(如 US, FR, UK, DE, ...
)。
Request 要求
curl 'https://api.column.com/entities/business/<entity_id>' \
-XPATCH \
-u :<YOUR API KEY> \
-H 'Content-Type: application/json' \
-d '{
"ein":"123456789",
"business_name":"Yellen Cocktails LLC",
"industry":"housing",
"website":"column.com",
"legal_type":"corporation",
"address":{
"line_1":"555 California Street",
"city":"San Francisco",
"state":"CA",
"country_code":"US"
},
"beneficial_owners":[
{
"date_of_birth":"1990-01-01",
"first_name":"Oliver",
"last_name":"Hockey",
"ssn":"999999999",
"email":"oli@column.com",
"is_control_person":true,
"is_beneficial_owner":true,
"job_title":"CEO",
"address":{
"line_1":"101 Market St",
"line_2":"Suite 1913",
"city":"San Francisco",
"state":"CA",
"postal_code":"94105",
"country_code":"US"
}
}
]
}'
Response 回应
{
"business_details": {
"account_usage": "",
"address": {
"city": "San Francisco",
"country_code": "US",
"line_1": "1110 Gorgas Avenue",
"line_2": "Suite 1000",
"postal_code": "94109",
"state": "CA"
},
"beneficial_owners": [
{
"address": {
"city": "San Francisco",
"country_code": "US",
"line_1": "999 Bay Street",
"line_2": "",
"postal_code": "94109",
"state": "CA"
},
"date_of_birth": "1989-01-01",
"drivers_license": null,
"email": "mbakery@bakery.com",
"first_name": "Sam",
"last_name": "Smith",
"middle_name": "Test",
"national_id": null,
"passport": {},
"ssn": "999999999"
}
],
"business_name": "Maries Bakery",
"countries_of_operation": null,
"year_of_incorporation": "2022",
"description": "Bakery",
"ein": "111111111",
"industry": "",
"legal_type": "",
"payment_volumes": null,
"registration_id": {
"country_code": "US",
"number": "111111111"
},
"state_of_incorporation": "CA",
"website": "acme.com"
},
"documents": [],
"id": "enti_2dk2oXqPcB5Xb5wFpnrg50F7BeD",
"is_root": false,
"review_reasons": [],
"type": "BUSINESS",
"verification_status": "VERIFIED"
}
Get an entity by ID
通过 ID 获取实体
GET
/entities/<entity_id>
Retrieve a single legal entity by its ID.
根据 ID 检索单个法律实体。
path parameters 路径参数
entity_id
string 字符串
Required 需要
ID of the entity you're requesting. Depending on the entity type, either the business or person object will be returned.
您所请求的实体的 ID。根据实体类型,将返回业务或个人对象。
Request 要求
curl 'https://api.column.com/entities/<entity_id>' \
-u :<YOUR API KEY>
Response 回应
{
"business_details": {
"address": {
"city": "San Francisco",
"country_code": "US",
"line_1": "555 California Street",
"line_2": "",
"postal_code": "",
"state": "CA"
},
"beneficial_owners": [
{
"address": {
"city": "San Francisco",
"country_code": "US",
"line_1": "101 Market St",
"line_2": "Suite 1913",
"postal_code": "94105",
"state": "CA"
},
"date_of_birth": "1990-01-01",
"email": "oliver@column.com",
"first_name": "Oliver",
"last_name": "Hockey",
"middle_name": "",
"passport": {},
"ssn": "999999999",
"drivers_license": null,
"national_id": null
}
],
"business_name": "Yellen Cocktails LLC",
"ein": "123456789",
"registration_id": {
"number": "123456789",
"country_code": "US"
},
"industry": "",
"legal_type": "corporation",
"website": "column.com"
},
"documents": [],
"id": "enti_2Q1fIwKjnf7TmZP37mAuKjWXB2o",
"is_root": false,
"review_reasons": [],
"type": "BUSINESS",
"verification_status": "VERIFIED"
}
Delete an entity 删除实体
DELETE 删除
/entities/<entity_id>
Delete the underlying entity.
删除底层实体。
Removing entities 删除实体
Entities can only be deleted if all their underlying accounts are deleted. Accounts can only be deleted when they have a $0 balance.
只有删除了所有相关账户,才能删除实体。账户只有在余额为 0 时才能删除。
path parameters 路径参数
entity_id
string 字符串
Required 需要
ID of the entity you're deleting.
您要删除的实体的 ID。
Request 要求
curl 'https://api.column.com/entities/<entity_id>' \
-XDELETE \
-u :<YOUR API KEY>
Response 回应
{}
List all entities 列出所有实体
GET
/entities /实体
Retrieve all entities on your platform. Filtered results can be retrieved with extra parameters in the query (`type`, `name`, etc.).
检索平台上的所有实体。可在查询中使用额外参数(`类型`、`名称`等)检索过滤后的结果。
query parameters 查询参数
limit 限额
int32
Optional 可选
A limit of the number of objects to be returned, between 1
and 100
. The default is 10
.
返回对象的数量限制,介于 1
和 100
之间。默认值为 10
。
starting_after 起始
string 字符串
Optional 可选
A cursor for use in pagination. starting_after
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with foo_ZXhhbXBsZQo
, your subsequent call can include starting_after=foo_ZXhhbXBsZQo
in order to fetch the next page of the list.
starting_after
是一个 ID,它定义了你在列表中的位置。例如,如果您发出列表请求并收到 20 个对象,以 foo_ZXhhbXBsZQo
结尾,那么您的后续调用就可以包含 starting_after=foo_ZXhhbXBsZQo
,以便获取列表的下一页。
ending_before 结束前
string 字符串
Optional 可选
A cursor for use in pagination. ending_before
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, starting with foo_ZXhhbXBsZQo=
, your subsequent call can include ending_before=foo_ZXhhbXBsZQo=
in order to fetch the previous page of the list.
ending_before
是一个 ID,它定义了你在列表中的位置。例如,如果您发出列表请求并收到 20 个对象,从 foo_ZXhhbXBsZQo=
开始,您的后续调用可以包括 ending_before=foo_ZXhhbXBsZQo=
,以便获取列表的前一页。
created.gt 创建.gt
date-time 日期时间
Optional 可选
Return results where the specified time field is greater than this value.
返回指定时间字段大于此值的结果。
created.gte 创建.gte
date-time 日期时间
Optional 可选
Return results where the specified time field is greater than or equal to this value.
返回指定时间字段大于或等于此值的结果。
created.lt 创建.lt
date-time 日期时间
Optional 可选
Return results where the specified time field is less than this value.
返回指定时间字段小于此值的结果。
created.lte 创建.lte
date-time 日期时间
Optional 可选
Return results where the specified time field is less than or equal to this value.
返回指定时间字段小于或等于此值的结果。
type 类型
string 字符串
Optional 可选
Return results with this entity type, either PERSON
or BUSINESS
.
返回该实体类型的结果, PERSON
或 BUSINESS
。
verification_status 验证状态
string 字符串
Optional 可选
Return results with this verification status.
返回具有此验证状态的结果。
is_root
boolean 布尔
Optional 可选
Indicates if the entity is the root entity of the platform.
表示该实体是否是平台的根实体。
name 名字
string 字符串
Optional 可选
Return entities with this name.
返回具有此名称的实体。
Request 要求
curl 'https://api.column.com/entities' \
-u :<YOUR API KEY>
Response 回应
{
"entities": [
{
"documents": [],
"id": "enti_2NkTtT5NI3Lh0LpjpvxO4M2AZHd",
"is_root": false,
"name": "Oliver Smith Hockey",
"review_reasons": [],
"type": "PERSON",
"verification_status": "VERIFIED"
},
{
"documents": [],
"id": "enti_2MCE4Cgh2Sl5ttZfnXYwzmfik0c",
"is_root": false,
"name": "Jim's Bakery",
"review_reasons": [],
"type": "BUSINESS",
"verification_status": "VERIFIED"
},
{
"documents": [],
"id": "enti_25n5phSY8StZxU4C2Y7gAREGUdB",
"is_root": false,
"name": "Bruce Smith Hockey",
"review_reasons": [],
"type": "PERSON",
"verification_status": "VERIFIED"
},
{
"documents": [],
"id": "enti_25FtFWv8n9rHaOoL3ZYttfEAr9k",
"is_root": false,
"name": "Yellen Cocktails LLC",
"review_reasons": [],
"type": "BUSINESS",
"verification_status": "VERIFIED"
},
{
"documents": [],
"id": "enti_23ZaVYnHLsOdd1MIQJ0uQfp9cgO",
"is_root": true,
"name": "Sam Smith",
"review_reasons": [],
"type": "PERSON",
"verification_status": "VERIFIED"
},
{
"documents": [],
"id": "enti_23ZT8vsfjNkjTFEN6c3OBrX9BUt",
"is_root": false,
"name": "Andrew Jackson",
"review_reasons": [],
"type": "PERSON",
"verification_status": "VERIFIED"
}
],
"has_more": false
}
Submit a document 提交文件
POST 职位
/entities/<entity_id>/documents
Submit a supporting document for manual review of an entity.
为人工审核实体提交证明文件。
path parameters 路径参数
entity_id
string 字符串
Required 需要
ID of the entity for which a supporting document is being submitted.
提交证明文件的实体的 ID。
body parameters 机体参数
document_front_id
string 字符串
Required 需要
ID of the entity for which a supporting document is being submitted.
提交证明文件的实体的 ID。
Accepted formats for person entities: PNG
, JPEG
, GIF
, and TIFF
.
个人实体的接受格式: PNG
, JPEG
, GIF
, 和 TIFF
。
document_back_id
string 字符串
Optional 可选
ID of the back of the document that is being submitted, starting with docu_. The document must be uploaded first via Document Upload API. This is only required for some forms of documentation. For most documents, only the front side is required.
提交文件背面的 ID,以 document_ 开头。文件必须先通过文件上传 API 上传。只有某些形式的文件才需要这样做。对于大多数文件,只需要正面。
Accepted formats for person entities: PNG
, JPEG
, GIF
, and TIFF
.
个人实体的接受格式: PNG
, JPEG
, GIF
, 和 TIFF
。
description 描述
string 字符串
Optional 可选
Description of why the document is being submitted for review. Maximum length: 127
characters.
说明提交审查文件的原因。最大长度: 127
字符。
Request 要求
curl 'https://api.column.com/entities/<entity_id>/documents' \
-XPOST \
-u :<YOUR API KEY> \
-d document_front_id=<docu_id> \
-d description='test document'
Response 回应
{
"documents": [
{
"created_at": "2022-03-01T17:36:57Z",
"description": "test document",
"document_id": "docu_25n6XQRGnGn2ozqjeGVNbclD3il",
"entity_id": "enti_25n5phSY8StZxU4C2Y7gAREGUdB"
}
],
"id": "enti_25n5phSY8StZxU4C2Y7gAREGUdB",
"is_root": false,
"person_details": {
"address": {
"city": "San Francisco",
"country_code": "US",
"line_1": "123 Federal Reserve Way",
"line_2": "",
"postal_code": "94123",
"state": "CA"
},
"date_of_birth": "1987-03-15",
"email": "andrew@column.com",
"first_name": "Alex",
"last_name": "Smith",
"middle_name": "",
"ssn": "123456789"
},
"review_reasons": [],
"type": "PERSON",
"verification_status": "VERIFIED",
"verification_tags": ["vouched_result_passed"]
}
Bank Account object 银行账户对象
A bank account is the object in the Column data model that has the ability to hold, send, and receive funds. Bank accounts are children of entities. An entity can have multiple bank accounts. Bank accounts can have one or multiple account numbers. Read about bank accounts in our data model section for more information.
银行账户是列数据模型中能够持有、发送和接收资金的对象。银行账户是实体的子实体。一个实体可以有多个银行账户。银行账户可以有一个或多个账号。有关银行账户的更多信息,请阅读数据模型部分。
object parameters 对象参数
balances 余额
object 反对
Lists all possible balance amounts for an account represented in the smallest unit of the currency.
列出以最小货币单位表示的账户所有可能的余额。
available_amount 可用金额
int64
This balance is the amount of money that is available to spend. If the account is not enabled for overdrafts, any requests to move money above this number will fail.
该余额是可用于消费的金额。如果账户未启用透支功能,任何超过该数字的转账请求都将失败。
holding_amount 持有金额
int64
The balance of money which is currently in a HOLD
state specified in the Create Book Transfer API.
创建账簿转账 API 中指定的当前处于 HOLD
状态的资金余额。
locked_amount 锁定金额
int64
Only applicable for root accounts. The locked balance is posted on the account but cannot be withdrawn.
仅适用于根账户。锁定的余额会记录在账户上,但不能提取。
pending_amount 待处理金额
int64
The total amount of transfers that are in a pending state. These transfers will affect the available_balance unless they are canceled prior to completion.
处于等待状态的转账总额。这些转账将影响可用余额,除非在完成前取消转账。
bic
string 字符串
The Swift BIC code for this bank account for international wire payments.
该银行账户用于国际电汇付款的 Swift BIC 代码。
created_at 创建时间
string 字符串
The timestamp at which the bank account was created.
银行账户创建的时间戳。
currency_code 货币代码
string 字符串
Currency of the balances in the account. For all amounts this will be USD
.
账户余额的货币。所有金额均为 USD
。
default_account_number 默认账号
string 字符串
The externally facing default account number tied to this bank account.
与该银行账户绑定的对外默认账号。
default_account_number_id
默认账号
string 字符串
The default account number ID tied to this account.
与此账户绑定的默认账号 ID。
description 描述
string 字符串
A name for the bank account (mininum: 3
characters)
银行账户名称(最少: 3
个字符)
id
string 字符串
Unique ID for this account.
该账户的唯一 ID。
is_overdraftable
boolean 布尔
Whether the account can be overdrafted, must include a overdraft_reserve_account_id
账户是否可以透支,必须包括以下内容 overdraft_reserve_account_id
overdraft_reserve_account_id
透支储备金账户 ID
string 字符串
The overdraft reserve account that this account linked to. If is_overdraftable: true
then this field is required.
该账户链接的透支储备金账户。如果 is_overdraftable: true
,则该字段为必填字段。
owners 车主
array 矩阵
List of entity_id
's which are tied to this bank account
与该银行帐户绑定的 entity_id
清单
routing_number 路由编号
string 字符串
The 9-digit ABA routing number for this bank account.
该银行账户的 9 位数 ABA 路由号码。
type 类型
string 字符串
Bank Account type. Can be CHECKING
, OVERDRAFT_RESERVE
, or PROGRAM_RESERVE
银行账户类型。可以是 CHECKING
, OVERDRAFT_RESERVE
, 或 PROGRAM_RESERVE
display_name 显示名称
string 字符串
The display name for the bank account. Display name is an account nickname used on Column's Dashboard.
银行账户的显示名称。显示名称是 Column 控制面板上使用的账户昵称。
Bank Account object 银行账户对象
{
"balances": {
"available_amount": 5100,
"holding_amount": 0,
"locked_amount": 0,
"pending_amount": 0
},
"bic": "CLNOUS66",
"created_at": "2021-10-14T17:50:21Z",
"currency_code": "USD",
"default_account_number": "123456789012345",
"default_account_number_id": "acno_2YHAWG9FTCxtL5emK1oVKCOx7fk",
"description": "John Doe",
"id": "bacc_2YHAXVyuS2xcJW12Buh9zsxV7vC",
"is_overdraftable": false,
"overdraft_reserve_account_id": "",
"owners": [
"enti_2YHAYW65t2fEna7uxll10OHzoty"
],
"routing_number": "121145307",
"type": "CHECKING"
}
Create a new bank account
创建新银行账户
POST 职位
/bank-accounts
Creates a new bank account under an entity.
在实体下创建新的银行账户。
body parameters 机体参数
description 描述
string 字符串
Required 需要
A name for the bank account (minimum of three characters)
银行账户名称(至少三个字符)
entity_id
string 字符串
Required 需要
The entity to create the account under
创建账户的实体
is_overdraftable
boolean 布尔
Optional 可选
Whether the account can be overdrafted, must include a overdraft_reserve_account_id
账户是否可以透支,必须包含一个 overdraft_reserve_account_id
overdraft_reserve_account_id
透支储备金账户 ID
string 字符串
Optional 可选
The overdraft reserve account that this account linked to. If `is_overdraftable: true` then this field is required
该账户关联的透支储备金账户。如果 "is_overdraftable:true "为必填字段,则该字段为必填字段
display_name 显示名称
string 字符串
Optional 可选
The display name for the bank account. Display name is an account nickname used on Column's Dashboard.
银行账户的显示名称。显示名称是 Column 控制面板上使用的账户昵称。
Request 要求
curl 'https://api.column.com/bank-accounts' \
-XPOST \
-u :<YOUR API KEY> \
-d description="Travel Checking" \
-d entity_id="<entity_id>"
Response 回应
{
"balances": {
"available_amount": 0,
"holding_amount": 0,
"locked_amount": 0,
"pending_amount": 0
},
"bic": "CLNOUS66",
"created_at": "2021-10-14T17:50:21Z",
"currency_code": "USD",
"default_account_number": "123456789012345",
"default_account_number_id": "acno_2YHAWG9FTCxtL5emK1oVKCOx7fk",
"description": "Travel Checking",
"id": "bacc_2YHAXVyuS2xcJW12Buh9zsxV7vC",
"is_overdraftable": false,
"overdraft_reserve_account_id": "",
"owners": [
"enti_2YHAYW65t2fEna7uxll10OHzoty"
],
"routing_number": "121145307",
"type": "CHECKING"
}
List all bank accounts 列出所有银行账户
GET
/bank-accounts
List all bank accounts under the platform. Filtered results can be retrieved with extra parameters in the query.
列出平台下的所有银行账户。可在查询中使用额外参数检索过滤后的结果。
query parameters 查询参数
entity_id
string 字符串
Optional 可选
List all accounts that belong to the entity with the entity_id
.
列出属于 entity_id
的实体的所有账户。
is_overdraftable
boolean 布尔
Optional 可选
List all accounts that are overdraftable.
列出可透支的所有账户。
type 类型
string 字符串
Optional 可选
Bank Account type. Can be CHECKING
, OVERDRAFT_RESERVE
, or PROGRAM_RESERVE
.
银行账户类型。可以是 CHECKING
, OVERDRAFT_RESERVE
, 或 PROGRAM_RESERVE
。
overdraft_reserve_account_id
透支储备金账户 ID
string 字符串
Optional 可选
List all bank accounts with the given overdraft_reserve_account_id
.
请列出所有银行账户, overdraft_reserve_account_id
。
limit 限额
int32
Optional 可选
A limit of the number of objects to be returned, between 1
and 100
. The default is 10
.
返回对象的数量限制,介于 1
和 100
之间。默认值为 10
。
starting_after 起始
string 字符串
Optional 可选
A cursor for use in pagination. starting_after
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with foo_ZXhhbXBsZQo
, your subsequent call can include starting_after=foo_ZXhhbXBsZQo
in order to fetch the next page of the list.
starting_after
是一个 ID,它定义了你在列表中的位置。例如,如果您发出列表请求并收到 20 个对象,以 foo_ZXhhbXBsZQo
结尾,那么您的后续调用就可以包含 starting_after=foo_ZXhhbXBsZQo
,以便获取列表的下一页。
ending_before 结束前
string 字符串
Optional 可选
A cursor for use in pagination. ending_before
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, starting with foo_ZXhhbXBsZQo=
, your subsequent call can include ending_before=foo_ZXhhbXBsZQo=
in order to fetch the previous page of the list.
ending_before
是一个 ID,它定义了你在列表中的位置。例如,如果您发出列表请求并收到 20 个对象,从 foo_ZXhhbXBsZQo=
开始,您的后续调用可以包括 ending_before=foo_ZXhhbXBsZQo=
,以便获取列表的前一页。
created.gt 创建.gt
date-time 日期时间
Optional 可选
Return results where the specified time field is greater than this value.
返回指定时间字段大于此值的结果。
created.gte 创建.gte
date-time 日期时间
Optional 可选
Return results where the specified time field is greater than or equal to this value.
返回指定时间字段大于或等于此值的结果。
created.lt 创建.lt
date-time 日期时间
Optional 可选
Return results where the specified time field is less than this value.
返回指定时间字段小于此值的结果。
created.lte 创建.lte
date-time 日期时间
Optional 可选
Return results where the specified time field is less than or equal to this value.
返回指定时间字段小于或等于此值的结果。
Request 要求
curl 'https://api.column.com/bank-accounts?entity_id=<entity_id>' \
-u :<YOUR API KEY>
Response 回应
{
"bank_accounts": [
{
"balances": {
"available_amount": 0,
"holding_amount": 0,
"locked_amount": 0,
"pending_amount": 0
},
"bic": "CLNOUS66",
"created_at": "2021-10-14T17:50:21Z",
"currency_code": "USD",
"default_account_number": "123456789012345",
"default_account_number_id": "acno_2YHAWG9FTCxtL5emK1oVKCOx7fk",
"description": "Travel Checking",
"id": "bacc_2YHAXVyuS2xcJW12Buh9zsxV7vC",
"is_overdraftable": false,
"overdraft_reserve_account_id": "",
"owners": [
"enti_2YHAYW65t2fEna7uxll10OHzoty"
],
"routing_number": "121145307",
"type": "CHECKING"
}
],
"has_more": false
}
Get a bank account by ID
用身份证开立银行账户
GET
/bank-accounts/<bank_account_id>
Get a bank account by its id
根据 ID 获取银行账户
path parameters 路径参数
bank_account_id 银行账户 ID
string 字符串
Required 需要
The ID of the bank account you are looking up
您要查询的银行账户的 ID
Request 要求
curl 'https://api.column.com/bank-accounts/<bank_account_id>' \
-u :<YOUR API KEY>
Response 回应
{
"balances": {
"available_amount": 0,
"holding_amount": 0,
"locked_amount": 0,
"pending_amount": 0
},
"bic": "CLNOUS66",
"created_at": "2021-10-14T17:50:21Z",
"currency_code": "USD",
"default_account_number": "123456789012345",
"default_account_number_id": "acno_2YHAWG9FTCxtL5emK1oVKCOx7fk",
"description": "Travel Checking",
"id": "bacc_2YHAXVyuS2xcJW12Buh9zsxV7vC",
"is_overdraftable": false,
"overdraft_reserve_account_id": "",
"owners": [
"enti_2YHAYW65t2fEna7uxll10OHzoty"
],
"routing_number": "121145307",
"type": "CHECKING"
}
Update a bank account 更新银行账户
PATCH 补丁
/bank-accounts/<bank_account_id>
Updates a bank account by its id
按 ID 更新银行账户
path parameters 路径参数
bank_account_id 银行账户 ID
string 字符串
Required 需要
body parameters 机体参数
description 描述
string 字符串
Optional 可选
is_overdraftable
boolean 布尔
Optional 可选
Whether the account can be overdrafted, must include a overdraft_reserve_account_id
账户是否可以透支,必须包括以下内容 overdraft_reserve_account_id
overdraft_reserve_account_id
透支储备金账户 ID
string 字符串
Optional 可选
The overdraft reserve account that this account linked to if is_overdraftable
is true
如果 is_overdraftable
为 true,该账户与透支储备金账户关联
display_name 显示名称
string 字符串
Optional 可选
The display name for the bank account. Display name is an account nickname used on Column's Dashboard.
银行账户的显示名称。显示名称是 Column 控制面板上使用的账户昵称。
Request 要求
url 'https://api.column.com/bank-accounts/<bank_account_id>' \
-XPATCH \
-u :<YOUR API KEY> \
-d description="Travel Checking UPDATE"
Response 回应
{
"balances": {
"available_amount": 0,
"holding_amount": 0,
"locked_amount": 0,
"pending_amount": 0
},
"bic": "CLNOUS66",
"created_at": "2021-10-14T17:50:21Z",
"currency_code": "USD",
"default_account_number": "123456789012345",
"default_account_number_id": "acno_2YHAWG9FTCxtL5emK1oVKCOx7fk",
"description": "Travel Checking",
"id": "bacc_2YHAXVyuS2xcJW12Buh9zsxV7vC",
"is_overdraftable": false,
"overdraft_reserve_account_id": "",
"owners": [
"enti_2YHAYW65t2fEna7uxll10OHzoty"
],
"routing_number": "121145307",
"type": "CHECKING"
}
Delete a bank account 删除银行账户
DELETE 删除
/bank-accounts/<bank_account_id>
This deletes a bank account
删除银行账户
Removing accounts 删除账户
Bank Accounts can only be deleted when they have a $0 balance.
银行账户只有在余额为 0 时才能删除。
path parameters 路径参数
bank_account_id 银行账户 ID
string 字符串
Required 需要
Request 要求
curl 'https://api.column.com/bank-accounts/<bank_account_id>' \
-XDELETE \
-u :<YOUR API KEY>
Response 回应
{}
Bank Account Summary object
银行账户摘要对象
object parameters 对象参数
available_balance_credit 可用余额
string 字符串
Total credit amount in cents applied to available_balance
. Zero or positive.
适用于 available_balance
的贷记总额(美分)。零或正数。
available_balance_debit 可用余额借记
string 字符串
Total debit amount in cents applied to available_balance
. Zero or negative.
适用于 available_balance
的借方总金额(美分)。零或负数。
available_balance_close 可用余额关闭
string 字符串
Close available_balance
in cents at the end of effective_on
in time_zone
.
在 effective_on
结束时以美分为单位关闭 available_balance
, time_zone
。
currency 货币
string 字符串
The currency of the balances.
余额的货币。
effective_on
string 字符串
Effective date of the summary.
摘要的生效日期。
holding_balance_credit 持有余额
string 字符串
Total credit amount in cents applied to holding_balance
. Zero or positive.
适用于 holding_balance
的贷记总额(美分)。零或正数。
holding_balance_debit 持有余额借方
string 字符串
Total debit amount in cents applied to holding_balance
. Zero or negative.
适用于 holding_balance
的借方总金额(美分)。零或负数。
holding_balance_close 持有余额关闭
string 字符串
Close holding_balance
in cents at the end of effective_on
in time_zone
.
在 effective_on
结束时以美分为单位关闭 holding_balance
, time_zone
。
locked_balance_credit 锁定的余额
string 字符串
Total credit amount in cents applied to locked_balance
. Zero or positive.
适用于 locked_balance
的贷记总额(美分)。零或正数。
locked_balance_debit 锁定的余额借记
string 字符串
Total debit amount in cents applied to locked_balance
. Zero or negative.
适用于 locked_balance
的借方总金额(美分)。零或负数。
locked_balance_close 锁定平衡
string 字符串
Close locked_balance
in cents at the end of effective_on
in time_zone
.
在 effective_on
结束时以美分为单位关闭 locked_balance
, time_zone
。
pending_balance_credit 待定余额
string 字符串
Total credit amount in cents applied to pending_balance
. Zero or positive.
适用于 pending_balance
的贷记总额(美分)。零或正数。
pending_balance_debit 待处理余额借记
string 字符串
Total debit amount in cents applied to pending_balance
. Zero or negative.
适用于 pending_balance
的借方总金额(美分)。零或负数。
pending_balance_close 待结算关闭
string 字符串
Close pending_balance
in cents at the end of effective_on
in time_zone
.
在 effective_on
结束时以美分为单位关闭 pending_balance
, time_zone
。
time_zone 时区
string 字符串
Time zone of effective_on
to decide day boundaries. You can set your platform reporting time zone in Platform Settings on Dashboard.
effective_on
的时区来决定日界线。您可以在控制面板的平台设置中设置平台报告时区。
transaction_count 交易次数
int32
Total number of transactions on the day of effective_on
.
effective_on
当天的交易总数。
Bank Account Summary object
银行账户摘要对象
{
"effective_on": "2022-03-01",
"time_zone": "America/Los_Angeles",
"currency": "USD",
"transaction_count": 1,
"available_balance_credit": "100",
"available_balance_debit": "-200",
"available_balance_close": "300",
"pending_balance_credit": "400",
"pending_balance_debit": "-500",
"pending_balance_close": "600",
"locked_balance_credit": "700",
"locked_balance_debit": "-800",
"locked_balance_close": "900",
"holding_balance_credit": "1000",
"holding_balance_debit": "-1100",
"holding_balance_close": "1200"
}
Get bank account summary history
获取银行账户历史摘要
GET
/bank-accounts/<bank_account_id>/history
Get the summary history of a bank account. This endpoint returns a list of summaries, one summary per day, for a single bank account. You must set your platform reporting time zone in Platform Settings on Dashboard to use this endpoint (read more).
获取银行账户的历史摘要。此端点返回单个银行账户的摘要列表,每天一个摘要。必须在仪表板上的平台设置中设置平台报告时区才能使用此端点(了解更多信息)。
path parameters 路径参数
bank_account_id 银行账户 ID
string 字符串
Required 需要
The ID of the bank account you are looking up
您要查询的银行账户的 ID
query parameters 查询参数
from_date 从日期
string 字符串
Required 需要
Starting date of the history. Format: YYYY-MM-DD
.
历史开始日期。格式: YYYY-MM-DD
.
to_date 至日期
string 字符串
Required 需要
Ending date of the history. Format: YYYY-MM-DD
. Maximum date range: 31
days.
历史结束日期。格式: YYYY-MM-DD
。最大日期范围: 31
天。
Request 要求
curl 'https://api.column.com/bank-accounts/<bank_account_id>/history?from_date=2022-03-01&to_date=2022-03-02' \
-u :<YOUR API KEY>
Response 回应
{
"id": "bacc_27kpr2m6CsHkFYBocMa7l484DSd",
"history": [
{
"effective_on": "2022-03-01",
"time_zone": "America/Los_Angeles",
"currency": "USD",
"transaction_count": 1,
"available_balance_credit": "100",
"available_balance_debit": "-200",
"available_balance_close": "300",
"pending_balance_credit": "400",
"pending_balance_debit": "-500",
"pending_balance_close": "600",
"locked_balance_credit": "700",
"locked_balance_debit": "-800",
"locked_balance_close": "900",
"holding_balance_credit": "1000",
"holding_balance_debit": "-1100",
"holding_balance_close": "1200"
},
{
"effective_on": "2022-03-02",
"time_zone": "America/Los_Angeles",
"currency": "USD",
"transaction_count": 2,
"available_balance_credit": "200",
"available_balance_debit": "-300",
"available_balance_close": "400",
"pending_balance_credit": "500",
"pending_balance_debit": "-600",
"pending_balance_close": "700",
"locked_balance_credit": "800",
"locked_balance_debit": "-900",
"locked_balance_close": "1000",
"holding_balance_credit": "1100",
"holding_balance_debit": "-1200",
"holding_balance_close": "1300"
}
]
}
Bank Account Overdraft Alert
银行账户透支警报
A bank account overdraft alert is a notification when an account in your platform has been overdrawn and funds have been locked in your reserve accounts, or has been credited and locked funds in your reserve accounts have been released. Read more.
银行账户透支警报是指当您平台上的某个账户发生透支且资金被锁定在储备账户中,或已贷记且储备账户中的锁定资金已释放时发出的通知。更多信息
object parameters 对象参数
available_balance 可用余额
object 反对
The current available balance of the bank account after this alert.
发出警报后银行账户的当前可用余额。
cents 美分
int64
Amount in cents 金额(美分
currency_code 货币代码
string 字符串
Amount currency. The three-letter currency code defined in ISO 4217 (e.g. USD
)
金额货币。ISO 4217 中定义的三字母货币代码(如 USD
)
bank_account_id 银行账户 ID
string 字符串
ID of the bank account that is overdrawn or credited.
透支或贷记的银行账户 ID。
overdraft_amount 透支金额
object 反对
The amount that has been locked or released in the reserve account.
储备金账户锁定或释放的金额。
cents 美分
int64
Amount in cents 金额(美分
currency_code 货币代码
string 字符串
Amount currency. The three-letter currency code defined in ISO 4217 (e.g. USD
)
金额货币。ISO 4217 中定义的三字母货币代码(如 USD
)
reserve_account_id 储备账户 ID
string 字符串
ID of the reserve account in which funds are locked or released.
锁定或释放资金的储备金账户 ID。
transfer_id 转账
string 字符串
ID of transfer that triggered this alert.
触发此警报的传输 ID。
Bank Account object 银行账户对象
{
"available_balance": {
"cents": -240000,
"currency_code": "USD"
},
"bank_account_id": "bacc_2XJUlsjtGxHwFSyIxpWPmJ6a53q",
"overdraft_amount": {
"cents": 30000,
"currency_code": "USD"
},
"reserve_account_id": "bacc_2XJUltwuf4e3L5g8D6cljBP79os",
"transfer_id": "wire_2XJUlyL4xJ0BDynRsS0A2MHEtll"
}
Account number object 帐号对象
An account number is the child of a bank account. A bank account can have one or more account numbers. Think of account numbers as a pointer to a bank account. Account numbers will be used by external banks to transact with Column bank accounts. Read about account numbers in our data model section for more information.
账号是银行账户的子账号。一个银行账户可以有一个或多个账号。可以把帐号看作是银行帐户的指针。外部银行将使用帐号与列银行帐户进行交易。有关账号的更多信息,请阅读数据模型部分。
object parameters 对象参数
account_number 账号
string 字符串
The externally facing account number tied to this bank account.
与该银行账户绑定的对外账号。
bank_account_id 银行账户 ID
string 字符串
The Column bacc_id
tied to this bank account.
专栏 bacc_id
与该银行账户绑定。
bic
string 字符串
The Swift BIC code for this bank account for international wire payments.
该银行账户用于国际电汇付款的 Swift BIC 代码。
created_at 创建时间
string 字符串
The timestamp the account number was created.
创建账号的时间戳。
description 描述
string 字符串
A name for the account number (minimum of three characters)
账号名称(至少三个字符)
id
string 字符串
The unique id of the object
对象的唯一 ID
routing_number 路由编号
string 字符串
The 9-digit ABA routing number for this bank account.
该银行账户的 9 位数 ABA 路由号码。
Account Number object 账户编号对象
{
"account_number": "256783259046169",
"bank_account_id": "bacc_25nVQr05nZybpyEzw8j0wV6VRUh",
"bic": "CLNOUS66",
"created_at": "2022-03-01T20:09:42.949787176Z",
"description": "Travel Checking Account Number",
"id": "acno_25nacNsLD8qLI1Vc6x67sxFU27c",
"routing_number": "121145307"
}
Create a new account number
创建新账号
POST 职位
/bank-accounts/<bank_account_id>/account-numbers
Creates a new account number that points to the associated bank account
创建指向相关银行账户的新账号
path parameters 路径参数
bank_account_id 银行账户 ID
string 字符串
Required 需要
The bank account that you want the new account number to point to
您希望新账号指向的银行账户
body parameters 机体参数
description 描述
string 字符串
Optional 可选
A description for this account number
该账号的说明
Request 要求
curl 'https://api.column.com/bank-accounts/<bank_account_id>/account-numbers' \
-XPOST \
-u :<YOUR API KEY> \
-d description="Travel Checking Account Number"
Response 回应
{
"account_number": "256783259046169",
"bank_account_id": "bacc_25nVQr05nZybpyEzw8j0wV6VRUh",
"bic": "CLNOUS66",
"created_at": "2022-03-01T20:09:42.949787176Z",
"description": "Travel Checking Account Number",
"id": "acno_25nacNsLD8qLI1Vc6x67sxFU27c",
"routing_number": "121145307"
}
List all account numbers from a bank account
列出银行账户的所有账号
GET
/bank-accounts/<bank_account_id>/account-numbers
Lists all the account numbers that point to a specific bank account
列出指向特定银行账户的所有账号
path parameters 路径参数
bank_account_id 银行账户 ID
string 字符串
Required 需要
The bank account that you want the new account number to point to
您希望新账号指向的银行账户
query parameters 查询参数
limit 限额
int32
Optional 可选
A limit of the number of objects to be returned, between 1
and 100
. The default is 10
.
返回对象的数量限制,介于 1
和 100
之间。默认值为 10
。
starting_after 起始
string 字符串
Optional 可选
A cursor for use in pagination. starting_after
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with foo_ZXhhbXBsZQo
, your subsequent call can include starting_after=foo_ZXhhbXBsZQo
in order to fetch the next page of the list.
starting_after
是一个 ID,它定义了你在列表中的位置。例如,如果您发出列表请求并收到 20 个对象,以 foo_ZXhhbXBsZQo
结尾,那么您的后续调用就可以包含 starting_after=foo_ZXhhbXBsZQo
,以便获取列表的下一页。
ending_before 结束前
string 字符串
Optional 可选
A cursor for use in pagination. ending_before
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, starting with foo_ZXhhbXBsZQo=
, your subsequent call can include ending_before=foo_ZXhhbXBsZQo=
in order to fetch the previous page of the list.
ending_before
是一个 ID,它定义了你在列表中的位置。例如,如果您发出列表请求并收到 20 个对象,从 foo_ZXhhbXBsZQo=
开始,您的后续调用可以包括 ending_before=foo_ZXhhbXBsZQo=
,以便获取列表的前一页。
Request 要求
curl 'https://api.column.com/bank-accounts/<bank_account_id>/account-numbers' \
-u :<YOUR API KEY>
Response 回应
{
"account_numbers": [
{
"account_number": "256783259046169",
"bank_account_id": "bacc_25nVQr05nZybpyEzw8j0wV6VRUh",
"bic": "CLNOUS66",
"created_at": "2022-03-01T20:09:42.949787176Z",
"description": "Travel Checking Account Number",
"id": "acno_25nacNsLD8qLI1Vc6x67sxFU27c",
"routing_number": "121145307"
}
],
"has_more": true
}
Get an account number 获取账号
GET
/account-numbers/<account_number_id>
Lists all the account numbers that point to a specific bank account
列出指向特定银行账户的所有账号
path parameters 路径参数
account_number_id 账号
string 字符串
Required 需要
The id for the account number
账号的 ID
Request 要求
curl 'https://api.column.com/account-numbers/<account_number_id>' \
-u :<YOUR API KEY>
Response 回应
{
"account_number": "256783259046169",
"bank_account_id": "bacc_25nVQr05nZybpyEzw8j0wV6VRUh",
"bic": "CLNOUS66",
"created_at": "2022-03-01T20:09:42.949787176Z",
"description": "Travel Checking Account Number",
"id": "acno_25nacNsLD8qLI1Vc6x67sxFU27c",
"routing_number": "121145307"
}
Loan object 贷款对象
A loan is an object that lives under an entity, at the same level as a bank account. Just like entities can have multiple bank accounts, entities can have multiple loans. Loans are the foundation for many lending-oriented use cases such as charge cards and term loans. Read about loans in our data model section for more information.
贷款是实体下的一个对象,与银行账户处于同一级别。就像实体可以拥有多个银行账户一样,实体也可以拥有多个贷款。贷款是许多面向贷款的用例(如充值卡和定期贷款)的基础。有关贷款的更多信息,请阅读我们的数据模型部分。
object parameters 对象参数
balances 余额
object 反对
principal_charged_off 收取的本金
string 字符串
The balance of the loan which has been charged off.
已冲销的贷款余额。
principal_holding 持有本金
string 字符串
The balance of the loan which is in a holding
state.
处于 holding
状态的贷款余额。
principal_outstanding 杰出校长
string 字符串
The balance of the loan which is outstanding.
未偿还的贷款余额。
principal_paid 已付本金
string 字符串
The balance of the loan which has been paid.
已偿还的贷款余额。
charged_off_at 收费时间
string 字符串
The timestamp the loan was charged off.
注销贷款的时间戳。
created_at 创建时间
string 字符串
The timestamp the loan was created.
贷款创建的时间戳。
currency 货币
string 字符串
The currency of the loan. Currently only USD
is supported.
贷款货币。目前仅支持 USD
。
delinquent_at 拖欠日期
string 字符串
The timestamp the loan was marked as delinquent.
贷款被标记为拖欠的时间戳。
description 描述
string 字符串
The description of the loan in the Column dashboard.
专栏仪表板中的贷款描述。
disputed_at 有争议的日期
string 字符串
The timestamp the loan was marked as disputed.
贷款被标记为有争议的时间戳。
id
string 字符串
The id of the loan object.
贷款对象的 id。
is_revolving
boolean 布尔
Indicates whether or not the loan is revolving. If true
the loan can have multiple disbursements.
表示贷款是否可循环使用。如果 true
,贷款可以多次发放。
maturity_date 到期日
string 字符串
The maturity date of the loan.
贷款到期日。
max_principal_balance 最大本金余额
string 字符串
The max principal balance of the loan. This is akin to a credit limit. Disbursements will fail if the resulting principal will be above the max principal.
贷款的最大本金余额。这类似于信用额度。如果产生的本金高于最大本金,则付款将失败。
paid_off_at
string 字符串
The timestamp the loan is marked as paid off.
贷款标记为已还清的时间戳。
primary_signer_entity_id 主签名人实体 ID
string 字符串
The Column entity_id which the loan is related to.
与贷款相关的 Column entity_id。
status 地位
string 字符串
The current status of the loan. A loan can have a status of current
, delinquent
, charged_off
, in_dispute
, canceled
or paid_off
.
贷款的当前状态。贷款的状态可以是 current
, delinquent
, charged_off
, in_dispute
, canceled
或 paid_off
。
Loan object 贷款对象
{
"balances": {
"principal_charged_off": "0",
"principal_holding": "0",
"principal_outstanding": "0",
"principal_paid": "0"
},
"charged_off_at": null,
"created_at": "2022-03-15T23:18:24Z",
"currency": "USD",
"delinquent_at": null,
"description": "new_account",
"disputed_at": null,
"id": "loan_26RVIHzwLaCxVXmMLcUJyhFHT3b",
"is_revolving": true,
"maturity_date": "2021-01-01",
"max_principal_balance": "1000000",
"paid_off_at": null,
"primary_signer_entity_id": "enti_26RC4ARuBwDmxDlRX1ZX252YPfe",
"status": "current"
}
Create a new loan 创建新贷款
POST 职位
/loans /贷款
Creates a new loan under an entity.
在实体下创建新贷款。
body parameters 机体参数
currency 货币
string 字符串
Required 需要
The three-letter currency code defined in ISO 4217. e.g. USD
ISO 4217 中定义的三字母货币代码。 USD
description 描述
string 字符串
Required 需要
The description of the loan in the Column dashboard.
专栏仪表板中的贷款描述。
entity_id
boolean 布尔
Required 需要
The entity to create the loan under.
创建贷款的实体。
is_revolving
boolean 布尔
Required 需要
Indicates whether or not the loan is revolving. If true
the loan can have multiple disbursements.
表示贷款是否可循环使用。如果 true
,贷款可以多次发放。
maturity_date 到期日
string 字符串
Required 需要
The maturity date of the loan
贷款到期日
max_principal_balance 最大本金余额
string 字符串
Required 需要
The max principal balance of the loan in cents. This is akin to a credit limit. Disbursements will fail if the resulting principal will be above the max principal.
贷款的最大本金余额,单位为美分。这类似于信用额度。如果产生的本金高于最大本金,则付款将失败。
e.g. $1.75 would be represented by 175
.
例如,1.75 美元用 175
表示。
Request 要求
curl 'https://api.column.com/loans' \
-XPOST \
-u :<YOUR API KEY> \
-d description="sample loan" \
-d currency="USD" \
-d entity_id="enti_25n5phSY8StZxU4C2Y7gAREGUdB" \
-d is_revolving="true" \
-d maturity_date="2022-10-10" \
-d max_principal_balance="100000"
Response 回应
{
"balances": {
"principal_charged_off": "0",
"principal_holding": "0",
"principal_outstanding": "0",
"principal_paid": "0"
},
"charged_off_at": null,
"created_at": "2022-03-16T22:25:51Z",
"currency": "USD",
"delinquent_at": null,
"description": "sample loan",
"disputed_at": null,
"id": "loan_26UE1mcnJsRMTIJfwKFXqqF0xXo",
"is_revolving": true,
"maturity_date": "2022-10-10",
"max_principal_balance": "100000",
"paid_off_at": null,
"primary_signer_entity_id": "enti_25n5phSY8StZxU4C2Y7gAREGUdB",
"status": "current"
}
Update a loan 更新贷款
PATCH 补丁
/loans/<loan_id> /贷款<loan_id>
Updates a loan by its ID.
根据 ID 更新贷款。
path parameters 路径参数
loan_id
string 字符串
Required 需要
The ID of the loan you are looking up
您要查询的贷款 ID
body parameters 机体参数
description 描述
string 字符串
Optional 可选
The description of the loan in the Column dashboard.
专栏仪表板中的贷款描述。
is_revolving
boolean 布尔
Optional 可选
Indicates whether or not the loan is revolving. If true
the loan can have multiple disbursements.
表示贷款是否可循环使用。如果 true
,贷款可以多次发放。
maturity_date 到期日
string 字符串
Optional 可选
The maturity date of the loan.
贷款到期日。
max_principal_balance 最大本金余额
string 字符串
Optional 可选
The max principal balance of the loan in cents. This is akin to a credit limit. Disbursements will fail if the resulting principal will be above the max principal.
贷款的最大本金余额,单位为美分。这类似于信用额度。如果产生的本金高于最大本金,则付款将失败。
e.g. $1.75 would be represented by 175
.
例如,1.75 美元用 175
表示。
status 地位
string 字符串
Optional 可选
The current status of the loan. A loan can have a status of current
, delinquent
, charged_off
, in_dispute
, canceled
or paid_off
.
贷款的当前状态。贷款的状态可以是 current
, delinquent
, charged_off
, in_dispute
, canceled
或 paid_off
。
Request 要求
curl 'https://api.column.com/loans/<loan_id>' \
-XPATCH \
-u :<YOUR API KEY> \
-d max_principal_balance="50000000"
Response 回应
{
"balances": {
"principal_charged_off": "0",
"principal_holding": "0",
"principal_outstanding": "1500",
"principal_paid": "2000"
},
"charged_off_at": null,
"created_at": "2022-03-16T22:25:51Z",
"currency": "USD",
"delinquent_at": null,
"description": "sample loan",
"disputed_at": null,
"id": "loan_26UE1mcnJsRMTIJfwKFXqqF0xXo",
"is_revolving": true,
"maturity_date": "2022-10-10",
"max_principal_balance": "50000000",
"paid_off_at": null,
"primary_signer_entity_id": "enti_25n5phSY8StZxU4C2Y7gAREGUdB",
"status": "current"
}
Get a loan by ID
通过身份证获得贷款
GET
/loans/<loan_id> /贷款<loan_id>
Retrieve a single loan by its ID.
根据 ID 检索单笔贷款。
path parameters 路径参数
loan_id
string 字符串
Required 需要
The ID of the loan you are looking up
您要查询的贷款 ID
Request 要求
curl 'https://api.column.com/loans/<loan_id>' \
-u :<YOUR API KEY>
Response 回应
{
"balances": {
"principal_charged_off": "0",
"principal_holding": "0",
"principal_outstanding": "1000",
"principal_paid": "0"
},
"charged_off_at": null,
"created_at": "2022-03-16T22:25:51Z",
"currency": "USD",
"delinquent_at": null,
"description": "sample loan",
"disputed_at": null,
"id": "loan_26UE1mcnJsRMTIJfwKFXqqF0xXo",
"is_revolving": true,
"maturity_date": "2022-10-10",
"max_principal_balance": "100000",
"paid_off_at": null,
"primary_signer_entity_id": "enti_25n5phSY8StZxU4C2Y7gAREGUdB",
"status": "current"
}
List all loans 列出所有贷款
GET
/loans /贷款
List all loans under the platform. Filtered results can be retrieved with extra parameters in the query
列出平台下的所有贷款。可在查询中使用额外参数检索筛选后的结果
query parameters 查询参数
entity_id
string 字符串
Optional 可选
status 地位
string 字符串
Optional 可选
limit 限额
int32
Optional 可选
A limit of the number of objects to be returned, between 1
and 100
. The default is 10
.
返回对象的数量限制,介于 1
和 100
之间。默认值为 10
。
starting_after 起始
string 字符串
Optional 可选
A cursor for use in pagination. starting_after
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with foo_ZXhhbXBsZQo
, your subsequent call can include starting_after=foo_ZXhhbXBsZQo
in order to fetch the next page of the list.
starting_after
是一个 ID,它定义了你在列表中的位置。例如,如果您发出列表请求并收到 20 个对象,以 foo_ZXhhbXBsZQo
结尾,那么您的后续调用就可以包含 starting_after=foo_ZXhhbXBsZQo
,以便获取列表的下一页。
ending_before 结束前
string 字符串
Optional 可选
A cursor for use in pagination. ending_before
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, starting with foo_ZXhhbXBsZQo=
, your subsequent call can include ending_before=foo_ZXhhbXBsZQo=
in order to fetch the previous page of the list.
ending_before
是一个 ID,它定义了你在列表中的位置。例如,如果您发出列表请求并收到 20 个对象,从 foo_ZXhhbXBsZQo=
开始,您的后续调用可以包括 ending_before=foo_ZXhhbXBsZQo=
,以便获取列表的前一页。
created.gt 创建.gt
date-time 日期时间
Optional 可选
Return results where the specified time field is greater than this value.
返回指定时间字段大于此值的结果。
created.gte 创建.gte
date-time 日期时间
Optional 可选
Return results where the specified time field is greater than or equal to this value.
返回指定时间字段大于或等于此值的结果。
created.lt 创建.lt
date-time 日期时间
Optional 可选
Return results where the specified time field is less than this value.
返回指定时间字段小于此值的结果。
created.lte 创建.lte
date-time 日期时间
Optional 可选
Return results where the specified time field is less than or equal to this value.
返回指定时间字段小于或等于此值的结果。
Request 要求
curl 'https://api.column.com/loans?entity_id=enti_25n5phSY8StZxU4C2Y7gAREGUdB' \
-u :<YOUR API KEY>
Response 回应
{
"has_more": false,
"loans": [
{
"balances": {
"principal_charged_off": "0",
"principal_holding": "10000000",
"principal_outstanding": "9991500",
"principal_paid": "-52000"
},
"canceled_at": null,
"charged_off_at": null,
"created_at": "2022-03-16T22:25:51Z",
"currency": "USD",
"delinquent_at": null,
"description": "sample loan",
"disputed_at": null,
"id": "loan_26UE1mcnJsRMTIJfwKFXqqF0xXo",
"is_revolving": true,
"maturity_date": "2022-10-10",
"max_principal_balance": "50000000",
"paid_off_at": null,
"primary_signer_entity_id": "enti_25n5phSY8StZxU4C2Y7gAREGUdB",
"status": "current"
}
]
}
Create a disbursement 创建付款
POST 职位
/loans/disbursements /贷款/付款
Creates a disbursement for a loan.
创建贷款支付。
body parameters 机体参数
amount 数量
string 字符串
Required 需要
Amount (in cents) of the funds that will be disbursed.
将支付的资金数额(美分)。
e.g. $1.75 would be represented by 175
.
例如,1.75 美元用 175
表示。
bank_account_id 银行账户 ID
string 字符串
Required 需要
The bank account to which funds will be disbursed.
支付资金的银行账户。
currency 货币
string 字符串
Required 需要
The currency of the loan. Currently only USD
is supported.
贷款货币。目前仅支持 USD
。
description 描述
string 字符串
Required 需要
The description of the loan disbursement.
贷款发放说明。
hold 持有
boolean 布尔
Optional 可选
If true
, creates a disbursement in a hold
state. The disbursement will not be completed until the clear
API is called. Disbursements in a hold
state may be updated or canceled.
如果 true
,则在 hold
状态下创建付款。在调用 clear
API 之前,付款不会完成。处于 hold
状态的付款可以更新或取消。
loan_id
string 字符串
Required 需要
The ID of the loan to from which the disbursement is being made.
付款的贷款 ID。
details 详情
object 反对
Optional 可选
Transfer monitoring details
转账监控详情
sender_name 发件人名称
string 字符串
Optional 可选
Name of the sender 发件人姓名
merchant_name 商家名称
string 字符串
Optional 可选
Name of the merchant for this transaction
本次交易的商户名称
merchant_category_code 商家类别代码
string 字符串
Optional 可选
Category code for the merchant for this transaction
该交易的商户类别代码
authorization_method 授权方法
string 字符串
Optional 可选
Authorization method for this transaction
该交易的授权方法
website 网站
string 字符串
Optional 可选
Website for this transaction
本次交易的网站
internal_transfer_type 内部转账类型
string 字符串
Optional 可选
Transfer type in non-column systems
非柱式系统中的传输类型
statement_description 声明描述
string 字符串
Optional 可选
Line item on the customer statement for the transfer
客户账单上的转账细列项目
address 地址
object 反对
Required 需要
Addresses need to adhere to character validation, as addresses are used across multiple payment rails. Characters are validated according to the ACH Valid Character Specification.
地址需要遵守字符验证,因为地址会在多个支付系统中使用。字符根据 ACH 有效字符规范进行验证。
line_1 线_1
string 字符串
Required 需要
Address line 1 地址第 1 行
line_2 线_2
string 字符串
Optional 可选
Address line 2 地址第 2 行
city 城市
string 字符串
Required 需要
City 城市
state 国
string 字符串
Optional 可选
State name. For US addresses, this field is mandatory and only postal abbreviations (e.g. AL, CA, DE, ...
) are allowed.
州名。对于美国地址,该字段为必填字段,只允许使用邮政缩写(如 AL, CA, DE, ...
)。
postal_code 邮政编码
string 字符串
Optional 可选
Postal code 邮政编码
country_code 国家代码
string 字符串
Required 需要
ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
).
ISO 3166-1 Alpha-2 国家代码(如 US, FR, UK, DE, ...
)。
Request 要求
curl 'https://api.column.com/loans/disbursements' \
-XPOST \
-u :<YOUR API KEY> \
-d amount="1000" \
-d currency="USD" \
-d description="first disbursement" \
-d loan_id=loan_26UE1mcnJsRMTIJfwKFXqqF0xXo \
-d bank_account_id=bacc_25FyEyuKX3KlRAciUs3BzXag1RI
Response 回应
{
"account_number_id": "acno_25FyF49P2SE4PJJOmfx6kYCzkeI",
"amount": "1000",
"bank_account_id": "bacc_25FyEyuKX3KlRAciUs3BzXag1RI",
"created_at": "2022-03-17T16:00:24.686Z",
"currency": "USD",
"description": "first disbursement",
"effective_at": "2022-03-17T16:00:24.684711613Z",
"id": "ldsb_26WIHBrOhkhJNEBA48DKsxny8J9",
"loan_id": "loan_26UE1mcnJsRMTIJfwKFXqqF0xXo",
"status": "completed"
}
Update a disbursement 更新付款
PATCH 补丁
/loans/disbursements/<disbursement_id>
Update a disbursement by its ID. Disbursement must be in a "hold" state. Only the amount can be updated.
根据 ID 更新付款。付款必须处于 "保留 "状态。只能更新金额。
path parameters 路径参数
disbursement_id 付款id
string 字符串
Required 需要
The ID of the disbursement you want to update.
您要更新的付款 ID。
body parameters 机体参数
amount 数量
string 字符串
Required 需要
Amount (in cents) of the funds that will be disbursed.
将支付的资金数额(美分)。
e.g. $1.75 would be represented by 175
.
例如,1.75 美元用 175
表示。
currency 货币
string 字符串
Required 需要
The currency of the loan. Currently only USD
is supported.
贷款货币。目前仅支持 USD
。
Request 要求
curl 'https://api.column.com/loans/disbursements/<ldsb_id>' \
-XPATCH \
-u :<YOUR API KEY> \
-d amount="1500" \
-d currency="USD"
Response 回应
{
"account_number_id": "acno_25FyF49P2SE4PJJOmfx6kYCzkeI",
"amount": "1500",
"bank_account_id": "bacc_25FyEyuKX3KlRAciUs3BzXag1RI",
"created_at": "2022-03-17T16:39:20Z",
"currency": "USD",
"description": "first disbursement",
"effective_at": "2022-03-17T16:39:20Z",
"id": "ldsb_26WN0fvWcr9cR1tTzbTB3qbov8e",
"loan_id": "loan_26UE1mcnJsRMTIJfwKFXqqF0xXo",
"status": "hold"
}
Clear a disbursement 清除付款
POST 职位
/loans/disbursements/<disbursement_id>/clear
Clears a disbursement by its ID. Disbursements can only be cleared if they are in a "hold" state.
根据 ID 清除付款。只有处于 "保留 "状态的付款才能被清除。
path parameters 路径参数
disbursement_id 付款id
string 字符串
Required 需要
The ID of the disbursement to clear.
要清算的付款 ID。
body parameters 机体参数
amount 数量
string 字符串
Optional 可选
Updated amount (in cents) of the funds that will be disbursed.
将拨付资金的最新金额(美分)。
e.g. $1.75 would be represented by 175
.
例如,1.75 美元用 175
表示。
currency 货币
string 字符串
Optional 可选
The currency of the loan. Currently only USD
is supported.
贷款货币。目前仅支持 USD
。
Request 要求
curl 'https://api.column.com/loans/disbursements/<ldsb_id>/clear' \
-XPOST \
-u :<YOUR API KEY> \
-d amount="1500" \
-d currency="USD"
Response 回应
{
"account_number_id": "acno_25FyF49P2SE4PJJOmfx6kYCzkeI",
"amount": "1500",
"bank_account_id": "bacc_25FyEyuKX3KlRAciUs3BzXag1RI",
"created_at": "2022-03-17T16:39:20Z",
"currency": "USD",
"description": "first disbursement",
"effective_at": "2022-03-17T16:39:20Z",
"id": "ldsb_26WN0fvWcr9cR1tTzbTB3qbov8e",
"loan_id": "loan_26UE1mcnJsRMTIJfwKFXqqF0xXo",
"status": "completed"
}
Cancel a disbursement 取消付款
POST 职位
/loans/disbursements/<disbursement_id>/cancel
Cancels a disbursement by its ID. Only a disbursement in a "hold" state can be cancelled.
根据 ID 取消付款。只有处于 "保留 "状态的付款才能取消。
path parameters 路径参数
disbursement_id 付款id
string 字符串
Required 需要
The ID of the disbursement to clear.
要清算的付款 ID。
Request 要求
url 'https://api.column.com/loans/disbursements/<ldsb_id>/cancel' \
-XPOST \
-u :<YOUR API KEY>
Response 回应
{
"account_number_id": "acno_25FyF49P2SE4PJJOmfx6kYCzkeI",
"amount": "1000",
"bank_account_id": "bacc_25FyEyuKX3KlRAciUs3BzXag1RI",
"created_at": "2022-03-17T18:21:47Z",
"currency": "USD",
"description": "first disbursement",
"effective_at": "2022-03-17T18:21:47Z",
"id": "ldsb_26WZT7MtY2vxbrNHO9RHekeCIOo",
"loan_id": "loan_26UE1mcnJsRMTIJfwKFXqqF0xXo",
"status": "canceled"
}
Get a disbursement 获取付款
GET
/loans/disbursements/<disbursement_id>
Get a disbursement by its ID.
根据 ID 获取付款。
path parameters 路径参数
disbursement_id 付款id
string 字符串
Required 需要
The ID of the disbursement you are looking up.
您要查询的付款 ID。
Request 要求
curl 'https://api.column.com/loans/disbursements/<ldsb_id>' \
-u :<YOUR API KEY>
Response 回应
{
"account_number_id": "acno_25FyF49P2SE4PJJOmfx6kYCzkeI",
"amount": "1000",
"bank_account_id": "bacc_25FyEyuKX3KlRAciUs3BzXag1RI",
"created_at": "2022-03-17T18:21:47Z",
"currency": "USD",
"description": "first disbursement",
"effective_at": "2022-03-17T18:21:47Z",
"id": "ldsb_26WZT7MtY2vxbrNHO9RHekeCIOo",
"loan_id": "loan_26UE1mcnJsRMTIJfwKFXqqF0xXo",
"status": "canceled"
}
List all disbursements 列出所有付款
GET
/loans/disbursements /贷款/付款
List all disbursements under the platform. Filtered results can be retrieved with extra parameters in the query.
列出平台下的所有付款。可在查询中使用额外参数检索过滤后的结果。
query parameters 查询参数
loan_id
string 字符串
Optional 可选
bank_account_id 银行账户 ID
string 字符串
Optional 可选
limit 限额
int32
Optional 可选
A limit of the number of objects to be returned, between 1
and 100
. The default is 10
.
返回对象的数量限制,介于 1
和 100
之间。默认值为 10
。
starting_after 起始
string 字符串
Optional 可选
A cursor for use in pagination. starting_after
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with foo_ZXhhbXBsZQo
, your subsequent call can include starting_after=foo_ZXhhbXBsZQo
in order to fetch the next page of the list.
starting_after
是一个 ID,它定义了你在列表中的位置。例如,如果您发出列表请求并收到 20 个对象,以 foo_ZXhhbXBsZQo
结尾,那么您的后续调用就可以包含 starting_after=foo_ZXhhbXBsZQo
,以便获取列表的下一页。
ending_before 结束前
string 字符串
Optional 可选
A cursor for use in pagination. ending_before
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, starting with foo_ZXhhbXBsZQo=
, your subsequent call can include ending_before=foo_ZXhhbXBsZQo=
in order to fetch the previous page of the list.
ending_before
是一个 ID,它定义了你在列表中的位置。例如,如果您发出列表请求并收到 20 个对象,从 foo_ZXhhbXBsZQo=
开始,您的后续调用可以包括 ending_before=foo_ZXhhbXBsZQo=
,以便获取列表的前一页。
created.gt 创建.gt
date-time 日期时间
Optional 可选
Return results where the specified time field is greater than this value.
返回指定时间字段大于此值的结果。
created.gte 创建.gte
date-time 日期时间
Optional 可选
Return results where the specified time field is greater than or equal to this value.
返回指定时间字段大于或等于此值的结果。
created.lt 创建.lt
date-time 日期时间
Optional 可选
Return results where the specified time field is less than this value.
返回指定时间字段小于此值的结果。
created.lte
date-time
Optional
Return results where the specified time field is less than or equal to this value.
Request
curl 'https://api.column.com/loans/disbursements?loan_id=loan_26UE1mcnJsRMTIJfwKFXqqF0xXo' \
-u :<YOUR API KEY>
Response
{
"disbursements": [
{
"account_number_id": "acno_2781oeSJZNEtpG1cc9xWheur5SF",
"amount": "20000",
"bank_account_id": "bacc_2781ocmuIk4fcq818QRDoJ7hXlS",
"created_at": "2022-03-31T03:50:17Z",
"currency": "USD",
"description": "first disbursement",
"effective_at": "2022-03-31T03:50:17Z",
"id": "ldsb_278PD0e01VxKMfFajrGBmEmCdoJ",
"loan_id": "loan_26UE1mcnJsRMTIJfwKFXqqF0xXo",
"status": "completed"
},
{
"account_number_id": "acno_274RkerEeeYrNHCoRmkxcdCWz0c",
"amount": "20000",
"bank_account_id": "bacc_274RkcTicf4P3pZRWnCFM4tGzhT",
"created_at": "2022-03-29T21:18:27Z",
"currency": "USD",
"description": "first disbursement",
"effective_at": "2022-03-29T21:18:27Z",
"id": "ldsb_274oQyeBOsOoFe3k2HBv0vIGOgB",
"loan_id": "loan_26UE1mcnJsRMTIJfwKFXqqF0xXo",
"status": "completed"
}
],
"has_more": false
}
Create a payment
POST
/loans/payments
Creates a payment for a loan.
body parameters
principal_amount
string
Required
Amount (in cents) of the loan payment.
e.g. $1.75 would be represented by 175
.
bank_account_id
string
Required
The bank account from which the payment is originated. The balance of the bank account will decrease by the payment amount.
currency
string
Required
The currency of the loan. Currently only USD
is supported.
description
string
Required
The description of the loan payment.
loan_id
string
Required
The ID of the loan to which the payment is being made. The principal_outstanding
of the loan will decrease by the payment amount.
Request
curl 'https://api.column.com/loans/payments' \
-XPOST \
-u :<YOUR API KEY> \
-d principal_amount="1000" \
-d currency="USD" \
-d description="first payment" \
-d loan_id=loan_26UE1mcnJsRMTIJfwKFXqqF0xXo \
-d bank_account_id=bacc_25FyEyuKX3KlRAciUs3BzXag1RI
Response
{
"account_number_id": "acno_25FyF49P2SE4PJJOmfx6kYCzkeI",
"bank_account_id": "bacc_25FyEyuKX3KlRAciUs3BzXag1RI",
"created_at":"2023-07-07T21:46:43.093Z"
"currency": "",
"description": "first payment",
"id": "lpmt_26WKSHYQoJvPEaGn149tlduSaja",
"loan_id": "loan_26UE1mcnJsRMTIJfwKFXqqF0xXo",
"principal_amount": "1000",
"status": "completed"
}
Get a payment
GET
/loans/payments/<payment_id>
Get a payment by its ID.
path parameters
payment_id
string
Required
The ID of the payment you are looking up.
Request
curl 'https://api.column.com/loans/payments/<lpmt_id>' \
-u :<YOUR API KEY>
Response
{
"account_number_id": "acno_25FyF49P2SE4PJJOmfx6kYCzkeI",
"bank_account_id": "bacc_25FyEyuKX3KlRAciUs3BzXag1RI",
"created_at": "2022-03-17T18:21:47Z",
"currency": "",
"description": "first payment",
"id": "lpmt_26WaF5JrqUEXT1yhabNOfoCf6fp",
"loan_id": "loan_26UE1mcnJsRMTIJfwKFXqqF0xXo",
"principal_amount": "1000",
"status": "completed"
}
List all payments
GET
/loans/payments
List all payments under the platform. Filtered results can be retrieved with extra parameters in the query.
query parameters
loan_id
string
Optional
bank_account_id
string
Optional
limit
int32
Optional
A limit of the number of objects to be returned, between 1
and 100
. The default is 10
.
starting_after
string
Optional
A cursor for use in pagination. starting_after
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with foo_ZXhhbXBsZQo
, your subsequent call can include starting_after=foo_ZXhhbXBsZQo
in order to fetch the next page of the list.
ending_before
string
Optional
A cursor for use in pagination. ending_before
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, starting with foo_ZXhhbXBsZQo=
, your subsequent call can include ending_before=foo_ZXhhbXBsZQo=
in order to fetch the previous page of the list.
created.gt
date-time
Optional
Return results where the specified time field is greater than this value.
created.gte
date-time
Optional
Return results where the specified time field is greater than or equal to this value.
created.lt
date-time
Optional
Return results where the specified time field is less than this value.
created.lte
date-time
Optional
Return results where the specified time field is less than or equal to this value.
Request
curl 'https://api.column.com/loans/payments?loan_id=loan_26UE1mcnJsRMTIJfwKFXqqF0xXo' \
-u :<YOUR API KEY>
Response
{
"has_more": false,
"payments": [
{
"account_number_id": "acno_2781oeSJZNEtpG1cc9xWheur5SF",
"bank_account_id": "bacc_2781ocmuIk4fcq818QRDoJ7hXlS",
"created_at":"2023-07-07T21:46:43.093Z",
"currency": "USD",
"description": "first payment",
"id": "lpmt_2782JJaLBzAmF7qpSUTjBwxHy6B",
"loan_id": "loan_26UE1mcnJsRMTIJfwKFXqqF0xXo",
"principal_amount": "10000",
"status": "completed"
},
{
"account_number_id": "acno_274RkerEeeYrNHCoRmkxcdCWz0c",
"bank_account_id": "bacc_274RkcTicf4P3pZRWnCFM4tGzhT",
"created_at":"2023-05-01T02:24:23.047Z",
"currency": "USD",
"description": "first payment",
"id": "lpmt_274o2O54AEQU5vXwgjVyMEP7tiQ",
"loan_id": "loan_26UE1mcnJsRMTIJfwKFXqqF0xXo",
"principal_amount": "20000",
"status": "completed"
}
],
"has_more": false
}
Counterparty object
A counterparty is an external account that you can transfer money to and from. All ACH and Wire transfers originated by Column take in a counterparty_id
to identify the transfer destination. Once you have created a counterparty, you can send money to it (or pull from it)! A counterparty stores an external bank account and can also store additional transaction details, as desired or required. Read about counterparties in our data model section for more information.
object parameters
account_number
string
The account number for the bank account.
account_type
string
The type of the account number. Can be checking
or savings
.
address
object
Addresses need to adhere to character validation, as addresses are used across multiple payment rails. Characters are validated according to the ACH Valid Character Specification.
line_1
string
Address line 1
line_2
string
Address line 2
city
string
City
state
string
State name. For US addresses, this field is mandatory and only postal abbreviations (e.g. AL, CA, DE, ...
) are allowed.
postal_code
string
Postal code
country_code
string
ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
).
created_at
string
The timestamp the object was created.
description
string
Description of the counterparty visible only in your platform. Maximum length: 127
characters.
string
The email address of the beneficiary.
id
string
The unique id of the object
is_column_account
boolean
Indicates whether this counterparty account is actually a Column account.
legal_id
string
The legal ID (e.g., Tax ID, Cedula Juridica, etc.) of the beneficiary. This field is recommended for international wire transfers, and required in some countries. Maximum length: 127
characters.
legal_type
string
The legal entity type of the beneficiary. Can be business
, non_profit
, individual
, or sole_proprietor
. This field is recommended for international wire transfers, and required in some countries.
local_account_number
string
The local account number (e.g. Cuenta Cliente in Costa Rica) in the beneficiary's bank. This field is recommended for international wire transfers, and required in some countries. Maximum length: 63
characters.
local_bank_code
string
The local bank code of the beneficiary's bank (e.g., India IFSC, Australia BSB, China CNAPS, etc.). This field is recommended for international wire transfers, and required in some countries. Maximum length: 63
characters.
name
string
The counterparty name who owns the bank account. For domestic wires, only the first 35 characters are included in the wire message. For international wires, only the first 140 characters are included in the wire message. Additional characters will be truncated.
phone
string
The phone number of the beneficiary. This field is recommended for international wire transfers, and required in some countries. Maximum length: 31
characters.
Format for international wire transfers: \+[0-9]{1,3}-[0-9()+\-]{1,30}
(e.g. +44-(0)1223-333300
).
Format for domestic wire transfers:
+1-(650)123-4567
(US international phone number format)650-123-4567
(650)123-4567
(650) 123-4567
650 123 4567
6501234567
routing_number
string
The routing number of the bank.
routing_number_type
string
The type of the routing number. Can be aba
, bic
, or other
.
updated_at
string
The timestamp the object was last updated.
wire_drawdown_allowed
boolean
Whitelists counterparties for automatic approval of drawdown requests to Column via FedWire. If false, all inbound drawdown requests from this counterparty will require explicit approval.
Counterparty object
{
"account_number": "GB29NWBK60161331926819",
"account_type": "checking",
"address": {
"city": "New Winton",
"country_code": "GB",
"line_1": "96 Lairg Road",
"line_2": "",
"postal_code": "EH33 5ZN",
"state": ""
},
"created_at": "2023-07-07T22:31:30.859307801Z",
"description": "international_cpty",
"email": "john.doe@gmail.com",
"id": "cpty_2SGNjEY3ax4DaX4LgU72navTADL",
"is_column_account": false,
"legal_id": "GB1245643234",
"legal_type": "sole_proprietor",
"local_account_number": "876545678",
"local_bank_code": "GB123456",
"local_bank_country_code": "",
"local_bank_name": "",
"name": "John Doe",
"phone": "650-123-4567",
"routing_number": "NWBKGB2L",
"routing_number_type": "bic",
"updated_at": "2023-07-07T22:31:30.859307801Z",
"wire": {
"beneficiary_address": {
"city": "New Winton",
"country_code": "GB",
"line_1": "96 Lairg Road",
"line_2": "",
"postal_code": "EH33 5ZN",
"state": ""
},
"beneficiary_email": "john.doe@gmail.com",
"beneficiary_legal_id": "GB1245643234",
"beneficiary_name": "John Doe",
"beneficiary_phone": "650-123-4567",
"beneficiary_type": "sole_proprietor",
"local_account_number": "876545678",
"local_bank_code": "GB123456"
},
"wire_drawdown_allowed": false
}
Create a counterparty
POST
/counterparties
A counterparty is the legal entity on the other side of the transaction. Depending on the type of transaction, we may need to know more or less about them.
A domestic ACH only requires a counterparty's account and routing number. If you include a counterparty name, Column will by default populate receiver_name
on the ACH transfer request. Domestic and international wires require full name and address. Certain countries may require additional fields. Learn more about country-specific details here.
body parameters
routing_number
string
Required
The routing number of the bank.
routing_number_type
string
Optional
The type of the routing number. Can be aba
or bic
. Default value is aba
if this field is not set.
account_number
string
Required
The account number of the bank account.
account_type
string
Optional
The type of the account number. Can be checking
or savings
.
description
string
Optional
Description of the counterparty visible only in your platform. Maximum length: 127
characters.
wire_drawdown_allowed
boolean
Optional
Whitelists counterparties for automatic approval of drawdown requests to Column via FedWire. If false, all inbound drawdown requests from this counterparty will require explicit approval.
name
string
Optional
The account holder on the counterparty bank account. This field is not required to send ACH transfers, but is required to send domestic and international wires. For international wires, Must adhere to International Wire character validation . Column will truncate name
to a maximum length of 140
characters per SWIFT guidelines. For domestic wires, Must adhere to FedWire character validation . Column will truncate name
to 35
characters per Fedwire guidelines.
address
object
Optional
The address object is not required to send ACH transfers, but is required to send domestic and international wires.
line_1
string
Required
Address line 1
line_2
string
Optional
Address line 2
city
string
Required
City
state
string
Optional
State name. For US addresses, this field is mandatory and only postal abbreviations (e.g. AL, CA, DE, ...
) are allowed.
postal_code
string
Optional
Postal code
country_code
string
Required
ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
).
phone
string
Optional
The phone number of the beneficiary. This field is recommended for international wire transfers, and required in some countries. Maximum length: 31
characters.
Format for international wire transfers: \+[0-9]{1,3}-[0-9()+\-]{1,30}
(e.g. +44-(0)1223-333300
).
Format for domestic wire transfers:
+1-(650)123-4567
(US international phone number format)650-123-4567
(650)123-4567
(650) 123-4567
650 123 4567
6501234567
string
Optional
The email address of the beneficiary. This field is recommended for international wire transfers, and required in some countries. Maximum length: 127
characters.
legal_id
string
Optional
The legal ID (e.g., Tax ID, Cedula Juridica, etc.) of the beneficiary. This field is recommended for international wire transfers, and required in some countries. Maximum length: 127
characters. For international wires, Must adhere to International Wire character validation .
legal_type
string
Optional
The legal entity type of the beneficiary. Can be business
, non_profit
, individual
, or sole_proprietor
. This field is recommended for international wire transfers, and required in some countries. For international wires, Must adhere to International Wire character validation .
local_bank_code
string
Optional
The local bank code of the beneficiary's bank (e.g., India IFSC, Australia BSB, China CNAPS, etc.). This field is recommended for international wire transfers, and required in some countries. Maximum length: 63
characters. For international wires, Must adhere to International Wire character validation .
local_account_number
string
Optional
The local account number (e.g. Cuenta Cliente in Costa Rica) in the beneficiary's bank. This field is recommended for international wire transfers, and required in some countries. Maximum length: 63
characters. For international wires, Must adhere to International Wire character validation .
Request
curl 'https://api.column.com/counterparties' \
-XPOST \
-u :<YOUR API KEY> \
-d routing_number="AACDGB21" \
-d account_number="GB29NWBK60161331926819" \
-d routing_number_type="bic" \
-d account_type="checking" \
-d description="international_cpty" \
-d name="John Doe" \
-d phone="650-123-4567" \
-d email="john.doe@gmail.com" \
-d legal_id="GB1245643234" \
-d legal_type="sole_proprietor" \
-d local_bank_code="GB123456" \
-d local_account_number="876545678" \
-d "address[line_1]"="96 Lairg Road" \
-d "address[city]"="New Winton" \
-d "address[postal_code]"="EH33 5ZN" \
-d "address[country_code]"="GB"
Response
{
"account_number": "GB29NWBK60161331926819",
"account_type": "checking",
"address": {
"city": "New Winton",
"country_code": "GB",
"line_1": "96 Lairg Road",
"line_2": "",
"postal_code": "EH33 5ZN",
"state": ""
},
"created_at": "2023-07-07T22:31:30.859307801Z",
"description": "international_cpty",
"email": "john.doe@gmail.com",
"id": "cpty_2SGNjEY3ax4DaX4LgU72navTADL",
"is_column_account": false,
"legal_id": "GB1245643234",
"legal_type": "sole_proprietor",
"local_account_number": "876545678",
"local_bank_code": "GB123456",
"local_bank_country_code": "",
"local_bank_name": "",
"name": "John Doe",
"phone": "650-123-4567",
"routing_number": "NWBKGB2L",
"routing_number_type": "bic",
"updated_at": "2023-07-07T22:31:30.859307801Z",
"wire": {
"beneficiary_address": {
"city": "New Winton",
"country_code": "GB",
"line_1": "96 Lairg Road",
"line_2": "",
"postal_code": "EH33 5ZN",
"state": ""
},
"beneficiary_email": "john.doe@gmail.com",
"beneficiary_legal_id": "GB1245643234",
"beneficiary_name": "John Doe",
"beneficiary_phone": "650-123-4567",
"beneficiary_type": "sole_proprietor",
"local_account_number": "876545678",
"local_bank_code": "GB123456"
},
"wire_drawdown_allowed": false
}
List all counterparties
GET
/counterparties
Retrieve all counterparties under your developer account. Filtered results can be retrieved with extra parameters in the query (account_number
, routing_number
, etc.).
query parameters
limit
int32
Optional
A limit of the number of objects to be returned, between 1
and 100
. The default is 10
.
starting_after
string
Optional
A cursor for use in pagination. starting_after
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with foo_ZXhhbXBsZQo
, your subsequent call can include starting_after=foo_ZXhhbXBsZQo
in order to fetch the next page of the list.
ending_before
string
Optional
A cursor for use in pagination. ending_before
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, starting with foo_ZXhhbXBsZQo=
, your subsequent call can include ending_before=foo_ZXhhbXBsZQo=
in order to fetch the previous page of the list.
created.gt
date-time
Optional
Return results where the specified time field is greater than this value.
created.gte
date-time
Optional
Return results where the specified time field is greater than or equal to this value.
created.lt
date-time
Optional
Return results where the specified time field is less than this value.
created.lte
date-time
Optional
Return results where the specified time field is less than or equal to this value.
account_number
string
Optional
Return counterparties created with given account number.
routing_number
string
Optional
Return counterparties created with given routing number.
Request
curl 'https://api.column.com/counterparties' \
-u :<YOUR API KEY>
Response
{
"counterparties": [
{
"account_number": "GB29NWBK60161331926819",
"account_type": "checking",
"address": {
"city": "New Winton",
"country_code": "GB",
"line_1": "96 Lairg Road",
"line_2": "",
"postal_code": "EH33 5ZN",
"state": ""
},
"created_at": "2023-07-07T22:31:30.859307801Z",
"description": "international_cpty",
"email": "john.doe@gmail.com",
"id": "cpty_2SGNjEY3ax4DaX4LgU72navTADL",
"is_column_account": false,
"legal_id": "GB1245643234",
"legal_type": "sole_proprietor",
"local_account_number": "876545678",
"local_bank_code": "GB123456",
"local_bank_country_code": "",
"local_bank_name": "",
"name": "John Doe",
"phone": "650-123-4567",
"routing_number": "NWBKGB2L",
"routing_number_type": "bic",
"updated_at": "2023-07-07T22:31:30.859307801Z",
"wire": {
"beneficiary_address": {
"city": "New Winton",
"country_code": "GB",
"line_1": "96 Lairg Road",
"line_2": "",
"postal_code": "EH33 5ZN",
"state": ""
},
"beneficiary_email": "john.doe@gmail.com",
"beneficiary_legal_id": "GB1245643234",
"beneficiary_name": "John Doe",
"beneficiary_phone": "650-123-4567",
"beneficiary_type": "sole_proprietor",
"local_account_number": "876545678",
"local_bank_code": "GB123456"
},
"wire_drawdown_allowed": false
}
],
"has_more": true
}
Get a counterparty by ID
GET
/counterparties/<counterparty_id>
Retrieve a single counterparty by its ID.
path parameters
counterparty_id
string
Required
ID of the counterparty you're looking up.
Request
curl 'https://api.column.com/counterparties/<counterparty_id>' \
-u :<YOUR API KEY>
Response
{
"account_number": "GB29NWBK60161331926819",
"account_type": "checking",
"address": {
"city": "New Winton",
"country_code": "GB",
"line_1": "96 Lairg Road",
"line_2": "",
"postal_code": "EH33 5ZN",
"state": ""
},
"created_at": "2023-07-07T22:31:30.859307801Z",
"description": "international_cpty",
"email": "john.doe@gmail.com",
"id": "cpty_2SGNjEY3ax4DaX4LgU72navTADL",
"is_column_account": false,
"legal_id": "GB1245643234",
"legal_type": "sole_proprietor",
"local_account_number": "876545678",
"local_bank_code": "GB123456",
"local_bank_country_code": "",
"local_bank_name": "",
"name": "John Doe",
"phone": "650-123-4567",
"routing_number": "NWBKGB2L",
"routing_number_type": "bic",
"updated_at": "2023-07-07T22:31:30.859307801Z",
"wire": {
"beneficiary_address": {
"city": "New Winton",
"country_code": "GB",
"line_1": "96 Lairg Road",
"line_2": "",
"postal_code": "EH33 5ZN",
"state": ""
},
"beneficiary_email": "john.doe@gmail.com",
"beneficiary_legal_id": "GB1245643234",
"beneficiary_name": "John Doe",
"beneficiary_phone": "650-123-4567",
"beneficiary_type": "sole_proprietor",
"local_account_number": "876545678",
"local_bank_code": "GB123456"
},
"wire_drawdown_allowed": false
}
Delete a counterparty
DELETE
/counterparties/<counterparty_id>
Delete a counterparty
path parameters
counterparty_id
string
Required
ID of the counterparty you're deleting.
Request
curl 'https://api.column.com/counterparties/<counterparty_id>' \
-XDELETE \
-u :<YOUR API KEY>
Response
{}
Financial Institution object
object parameters
ach_eligible
bool
Indicates if an institution accepts ACH transfers or not.
check_eligible
bool
Indicates if an institution supports check deposits or not.
city
string
Institution's address city name.
country_code
string
ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
).
created_at
string
The timestamp the object was created.
full_name
string
Institution's official full name.
phone_number
string
Institution's phone number. Only available if ach_eligible = true
.
routing_number
string
Institution's routing number. Can be 9-digit ABA routing numbers, or 8/11-character BICs.
routing_number_type
string
The type of the routing number. Can be aba
or bic
, or other
.
short_name
string
Institution's short name.
state
string
Institution's address state code (e.g., CA)
street_address
string
Institution's street address. Only available if ach_eligible = true
.
updated_at
string
The timestamp the object was last updated.
wire_eligible
bool
Indicates if an institution accepts wire transfers or not.
wire_settlement_only
bool
Indicates if an institution can only accept bank-to-bank settlement transfers, but cannot accept customer transfers.
zip_code
string
Institution's address zip code. Only available if ach_eligible = true
.
Financial Institution object
{
"ach_eligible": true,
"check_eligible": true,
"city": "CHICO",
"country_code": "US",
"created_at": "2021-10-13T16:39:01Z",
"full_name": "COLUMN N.A.",
"phone_number": "5308795900",
"routing_number": "121145307",
"routing_number_type": "aba",
"short_name": "COLUMN NA",
"state": "CA",
"street_address": "1717 MANGROVE AVE # 100",
"updated_at": "2021-10-20T15:53:03Z",
"wire_eligible": true,
"wire_settlement_only": false,
"zip_code": "95926"
}
Get a financial institution
GET
/institutions/<routing_number>
Retrieve a single financial institution by its ABA number or BIC.
path parameters
routing_number
string
Required
ABA number or BIC of the financial institution you're requesting
Request
curl 'https://api.column.com/institutions/322271627' \
-u :<YOUR API KEY>
Response
{
"ach_eligible": true,
"check_eligible": true,
"city": "TAMPA",
"country_code": "US",
"created_at": "2021-10-03T00:01:08Z",
"full_name": "JPMORGAN CHASE BANK, NA",
"phone_number": "8134323700",
"realtime_eligible": false,
"routing_number": "021000021",
"routing_number_type": "aba",
"short_name": "JPMCHASE",
"state": "FL",
"street_address": "10430 HIGHLAND MANOR DRIVE",
"updated_at": "2024-06-07T12:34:00Z",
"wire_eligible": true,
"wire_settlement_only": false,
"zip_code": "33610"
}
List financial institutions
GET
/institutions
List all financial institutions. Filtered results can be retrieved with extra parameters in your queires.
query parameters
limit
int32
Optional
A limit of the number of objects to be returned, between 1
and 100
. The default is 10
.
starting_after
string
Optional
A cursor for use in pagination. starting_after
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with foo_ZXhhbXBsZQo
, your subsequent call can include starting_after=foo_ZXhhbXBsZQo
in order to fetch the next page of the list.
ending_before
string
Optional
A cursor for use in pagination. ending_before
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, starting with foo_ZXhhbXBsZQo=
, your subsequent call can include ending_before=foo_ZXhhbXBsZQo=
in order to fetch the previous page of the list.
country_code
string
Optional
ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
).
name
string
Optional
Case-insensitive keywords in full names of financial institutions.
routing_number_type
string
Optional
The type of the routing number. Can be aba
or bic
.
Request
curl 'https://api.column.com/institutions?routing_number_type=bic&name=victoria&country_code=GB' \
-u :<YOUR API KEY>
Response
{
"has_more": false,
"institutions": [
{
"ach_eligible": true,
"check_eligible": true,
"city": "TAMPA",
"country_code": "US",
"created_at": "2021-10-03T00:01:08Z",
"full_name": "JPMORGAN CHASE BANK, NA",
"phone_number": "8134323700",
"realtime_eligible": false,
"routing_number": "021000021",
"routing_number_type": "aba",
"short_name": "JPMCHASE",
"state": "FL",
"street_address": "10430 HIGHLAND MANOR DRIVE",
"updated_at": "2024-06-07T12:34:00Z",
"wire_eligible": true,
"wire_settlement_only": false,
"zip_code": "33610"
},
{
"ach_eligible": true,
"check_eligible": true,
"city": "MINNEAPOLIS",
"country_code": "US",
"created_at": "2021-10-13T16:40:48Z",
"full_name": "WELLS FARGO BANK",
"phone_number": "8007452426",
"realtime_eligible": false,
"routing_number": "011100106",
"routing_number_type": "aba",
"short_name": "",
"state": "MN",
"street_address": "MAC N9301-041",
"updated_at": "2024-06-04T17:54:50Z",
"wire_eligible": false,
"wire_settlement_only": false,
"zip_code": "55479"
}
...
]
}
IBAN validation object
object parameters
account_number
string
Account number in the financial institution.
bank_id
string
Local bank code of the financial institution in its country.
bic
string
BIC of the financial institution.
branch_id
string
Branch ID of the financial institution.
check_digits
string
Check digits of the IBAN.
country_code
string
ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
) of the financial institution.
iban
string
The IBAN you are validating
institution_name
string
Name of the financial institution.
national_id
string
National ID of the financial institution in its country, which usually consists of its bank_id
and branch_id
.
IBAN validation object
{
"account_number": "31926819",
"bank_id": "NWBK",
"bic": "NWBKGB2L",
"branch_id": "601613",
"check_digits": "29",
"country_code": "GB",
"iban": "GB29NWBK60161331926819",
"institution_name": "NATIONAL WESTMINSTER BANK PLC",
"national_id": "NWBK601613"
}
Validate an IBAN
GET
/iban/<iban>
Validate the format of an IBAN and if it is registered with the given financial institution. However, we cannot verify if the account is still open.
path parameters
iban
string
Required
IBAN you're requesting
Request
curl 'https://api.column.com/iban/GB29NWBK60161331926819' \
-u :<YOUR API KEY>
Response
{
"account_number": "31926819",
"bank_id": "NWBK",
"bic": "NWBKGB2L",
"branch_id": "601613",
"check_digits": "29",
"country_code": "GB",
"iban": "GB29NWBK60161331926819",
"institution_name": "NATIONAL WESTMINSTER BANK PLC",
"national_id": "NWBK601613"
}
ACH transfer object
The ACH transfer object represents the current state of a single ACH transfers originated by or received by Column. The ACH object will contain all relevant information about the specific transfer, which are described in the parameters below. Read about more about ACH transfers here.
object parameters
account_number_id
string
ID of the account number that is sending the transfer.
acknowledged_at
string
The timestamp at which an acknowledgement is received for a CCD or CTX ACH transfer.
allow_overdraft
boolean
Allow the account to go negative for the transfer. The bank account needs to have is_overdraftable
enabled with an overdraft reserve account linked to it.
amount
int64
Amount (in cents) of the funds that will be transferred between originator and counterparty accounts.
e.g. $1.75 would be represented by 175
.
bank_account_id
string
ID of the bank account that is sending the transfer.
cancelled_at
string
The timestamp at which the transfer is cancelled.
company_discretionary_data
string
This optional field allows you to include codes (one or more), of significance only to you, to enable specialized handling of the transfer. There is no standardized interpretation for the value of the field. Maximum length:20
characters.
CIE
: This field may contain the Biller's name.
CTX
: The Originator's bank account number may be placed in this field.
company_entry_description
string
You can use this optional field to provide the Receiver with a description of the purpose of the transfer. For example, “Gas bill”, “Reg. Salary”, “ins. prem.”, “Soc. Sec.”, “DTC”, “Trade Pay”, “PURCHASE”, etc.
Default value: "PAYMENT". Maximum length: 10 characters.
company_id
string
A 10-digit unique identifier used for identifying entities, called originators, collecting payments via ACH debit. If you would like to use a specific company ID when originating ACH transactions, please contact us.
company_name
string
The name of the originator company that initiated the ACH transfer.
completed_at
string
The timestamp at which the 60 day return window has passed for this ACH transfer, and it is officially completed.
counterparty_id
string
ID of the counterparty that will receive the transfer.
created_at
string
The timestamp at which the transfer request is created.
currency_code
string
The three-letter currency code defined in ISO 4217. e.g. USD
.
description
string
Description of the transfer visible only in your platform. Maximum length: 255
characters.
effective_on
string
Datetime (00:00AM
in Pacific Time zone) on which the transfer is effective. For incoming transfers, this is 00:00AM
on the Settlement Date of the transfer in PT timezone (more details).
entry_class_code
string
Standard Entry Class code of the transfer. More Details Here.
iat
object
This field provides additional IAT (International ACH Transfer) addenda information. More information here.
id
string
The unique id for this object
idempotency_key
string
The idempotency key specified in the ACH transfer.
initiated_at
string
The timestamp at which Column received your ACH request.
is_incoming
boolean
Indicates whether the ACH transfer was incoming (true
) or outgoing (false
).
is_on_us
boolean
Indicates whether or not the ACH transfer is coming from a Column bank account. If true
the request is processed immediately like a book transfer, and not sent to the Fed.
intermediary_financial_institutions
array
Applies only to IAT transfers. This is a List of intermediary institutions involved in an IAT transfer.
manual_review_at
string
The timestamp at which the ACH transfer went into the manual review state.
notification_of_changes
object
Details of Notifications of Change (NOCs) with the latest information of the counterparty. Available only with ach.outgoing_transfer.noc
events.
receiver_id
string
Latest accounting reference number by which the beneficiary should be referred by the originator.
routing_number
string
Latest routing number of the counterparty.
account_number
string
Latest account number of the counterparty.
nsf_deadline
string
For incoming ACH Debits and available only with ach.incoming_transfer.nsf
events. This is the deadline by which the receiver account must be funded to complete the incoming debit. Column will file an NSF return for this ACH transfer if the account is not funded by the nsf_deadline.
odfi_routing_number
string
The externally facing routing number for the ODFI that initiated the ACH Transfer.
payment_related_info
string
Provides additional information on the ACH transfer. It is usually up to 80 characters long but could be longer for CTX, ENR and TRX transfers.
receiver_id
string
This field contains the accounting reference number by which the Receiver is known to the Originator. It is included for further identification and for descriptive purposes.
For example, it may be the number shown on an invoice, statement, billhead, notice, or other communication as the reference for the Receiver to update account receivable records.
receiver_name
string
The name of the receiver, usually the name on the bank account of the Receiver.
Default value: beneficiary name of the counterparty. Maximum length: 22
characters.
return_contested_at
string
The timestamp at which the dishonored return for this transfer was contested by the RDFI.
return_details
array
Details of the return processing history (e.g., initiated, dishonored, dishonor contested, manual review, etc.). Available only with ach.*.returned
, ach.*.return_dishonored
or ach.*.return_contested
events.
return_dishonored_at
string
The timestamp at which the return for this transfer was dishonored by the ODFI.
return_dishonored_funds_unlocked_at
string
The timestamp at which the dishonored return funds are unlocked.
returned_at
string
The timestamp at which the ACH transfer is returned by the RDFI.
reversal_pair_transfer_id
string
If the transfer is the original transfer of an ACH Reversal, this field is the unique ID of the reversal transfer. If the transfer is the reversal transfer of an ACH Reversal, this field is the unique ID of the original transfer. Please refer to ACH Reversals for more details.
same_day
boolean
Specify if the transfer is a same-day ACH transfer. If it is set as true
, it takes precedence over effective_date
and overrides it.
settled_at
string
The timestamp at which the ACH was settled.
status
string
The current state of the ACH transfer. See Notifications and States for details. Possible values: INITIATED
, PENDING_SUBMISSION
, SUBMITTED
, SETTLED
, RETURNED
, COMPLETED
, CANCELED
, SCHEDULED
, PENDING_RETURN
, RETURN_DISHONORED
, RETURN_DISHONORED_FUNDS_UNLOCKED
, RETURN_CONTESTED
, MANUAL_REVIEW
, and MANUAL_REVIEW_APPROVED
.
submitted_at
string
The timestamp at which the ACH transfer was submitted to the Fed.
trace_number
string
The unique number assigned to every ACH entry by an ODFI which identifies that entry within a specific ACH file.
transaction_type_code
string
This is a required code on IAT transfers used to identify reason for payment. Possible values: ANN
, BUS
, DEP
, LOA
, MIS
, MOR
, PEN
, REM
, RLS
, SAL
, TAX
. See IAT transfers for details.
type
string
ACH transfer type: CREDIT
or DEBIT
. Learn more.
ultimate_beneficiary_counterparty_id
string
ID of the ultimate beneficiary counterparty that will receive the transfer. This is only required on outgoing IAT debits.
ultimate_originator_counterparty_id
string
ID of the ultimate originating counterparty that sent the transfer. This is only required on outgoing IAT credits.
updated_at
string
The timestamp at which the ACH transfer was lastly updated.
ACH Transfer object
{
"id": "acht_2HKbYE2th2sFioBxrRFOZL3IHR4",
"iat": null,
"type": "CREDIT",
"amount": 60000,
"status": "SUBMITTED",
"is_on_us": false,
"same_day": false,
"company_id": "9959349647",
"created_at": "2022-11-09T23:32:47Z",
"settled_at": null,
"updated_at": "2022-11-09T23:32:48Z",
"description": "",
"is_incoming": false,
"receiver_id": "",
"returned_at": null,
"cancelled_at": null,
"company_name": "COLUMN NA",
"completed_at": null,
"effective_on": "2022-11-10T08:00:00Z",
"initiated_at": "2022-11-09T23:32:47Z",
"nsf_deadline": null,
"submitted_at": "2022-11-09T23:32:48Z",
"trace_number": "121145300000005",
"currency_code": "USD",
"receiver_name": "CHASE ACCOUNT",
"return_details": [],
"acknowledged_at": null,
"allow_overdraft": false,
"bank_account_id": "bacc_2HKbY4W10hcBQBx5r42xMDEhv2K",
"counterparty_id": "cpty_2HKbYBePtS8z3zK32QvwKlIoIeK",
"idempotency_key": "",
"entry_class_code": "PPD",
"manual_review_at": null,
"account_number_id": "acno_2HKbY3eq0gPP1WaQLZShDk87JC4",
"funds_availability": "default",
"odfi_routing_number": "121145307",
"return_contested_at": null,
"payment_related_info": "payment addenda for COR testing",
"return_dishonored_at": null,
"return_dishonored_funds_unlocked_at": null,
"notification_of_changes": {
"receiver_id": "",
"routing_number": "241070530",
"account_number": "123456789"
},
"company_entry_description": "PAYMENT",
"reversal_pair_transfer_id": "",
"company_discretionary_data": "",
"ultimate_beneficiary_counterparty_id":"",
"ultimate_originator_counterparty_id":""
}
IAT transfer sub-object
object parameters
foreign_correspondent_bank_info
array
Provides additional details around foreign corresponding banks used in the IAT transfer.
foreign_payment_amount
string
The amount for which the transfer was originated by the Foreign ODFI. This will be in USD, since Column will receive IATs from a domestic correspondent bank.
foreign_trace_number
string
Contains the trace number assigned to the transfer in the originating national payments system.
odfi_branch_country_code
string
The two digit alphabetic country code which identifies the country in which the branch of the bank that originated the transfer is located.
odfi_identification
string
The routing number of the DFI originating the transfer.
odfi_identification_number_qualifier
string
The two digit numbering scheme used in the ODFI identification number. Possible values are 01
(National Clearing System Number), 02
(BIC Coder), or 03
(IBAN).
odfi_name
string
The name of the ODFI
originator_city_state_province
string
Contains the city, and if applicable the state or province of the originator.
originator_country_postal_code
string
Contains the postal code for the originator street address.
originator_name
string
Contains the name of the originator of the transaction.
originator_street_address
string
Contains the physical street address of the originator.
rdfi_branch_country_code
string
The two digit alphabetic country code which identifies the country in which the branch of the bank that received the transfer is located.
rdfi_identification
string
This field is used by the originator to insert its own number for tracing purposes.
rdfi_identification_number_qualifier
string
Thw two digit numbering scheme used in the RDFI identification number. Possible values are 01
(National Clearing System Number), 02
(BIC Coder), or 03
(IBAN)
rdfi_name
string
The name of the RDFI.
receiver_city_state_province
string
Contains the city, and if applicable the state or province of the receiver.
receiver_country_postal_code
string
Contains the postal code for the receiver street address.
receiver_identification_number
string
Contains the bank identification number of the DFI at which the receiver maintains their account.
receiver_street_address
string
Contains the physical street address of the receiver.
receiving_company_or_individual_name
string
Contains the name of the receiver of the transaction.
IAT transfer sub-object
{
"iat": {
"foreign_correspondent_bank_info": [{
"name": "name"
"identification_number_qualifier": "identification_number_qualifier"
"identification_number": "identification_number"
"branch_country_code": "branch_country_code"
}, ...],
"foreign_payment_amount": "11500",
"foreign_trace_number": "",
"odfi_branch_country_code": "IE",
"odfi_identification": "02800008",
"odfi_identification_number_qualifier": "01",
"odfi_name": "CITIBANK EUROPE PLC",
"originator_city_state_province": "LONDON*GB\\",
"originator_country_postal_code": "REDACTED",
"originator_name": "REDACTED",
"originator_street_address": "REDACTED",
"rdfi_branch_country_code": "US",
"rdfi_identification": "REDACTED",
"rdfi_identification_number_qualifier": "01",
"rdfi_name": "COLUMN N.A.",
"receiver_city_state_province": "x\\",
"receiver_country_postal_code": "US*74110\\",
"receiver_identification_number": "REDACTED",
"receiver_street_address": "REDACTED",
"receiving_company_or_individual_name": "REDACTED"
}
}
Create an ACH transfer
POST
/transfers/ach
Creates an ACH transfer between an account and a counterparty
.
body parameters
description
string
Optional
Description of the transfer visible only in your platform. Maximum length: 255
characters.
amount
int64
Required
Amount (in cents) of the funds that will be transferred between originator and counterparty accounts.
e.g. $1.75 would be represented by 175
.
currency_code
string
Required
The three-letter currency code defined in ISO 4217. e.g. USD
account_number_id
string
Optional
ID of the account number from which the transfer is sent. If no account_number_id
is specified, the default account number on a provided bank_account_id
is used.
account_number_id
or bank_account_id
is required.
bank_account_id
string
Optional
ID of the bank account from which the transfer is sent. If no account_number_id
is specified, the default account number on the bank_account_id
is used.
account_number_id
or bank_account_id
is required.
counterparty
object
Optional
Counterparty object to create a counterparty for the receiver of the transfer at transfer creation. Either counterparty
or counterparty_id
is required.
counterparty_id
string
Required
ID of the counterparty that will receive the transfer. Either counterparty
or counterparty_id
is required.
type
string
Required
ACH transfer type: CREDIT
or DEBIT
. Learn More.
effective_date
string
Optional
Date (format: YYYY-MM-DD
) on which the transfer will be effective
same_day
boolean
Optional
Specify if the transfer is a same-day ACH transfer. If it is set as true
, it takes precedence over effective_date
and overrides it.
company_discretionary_data
string
Optional
This optional field allows you to include codes (one or more), of significance only to you, to enable specialized handling of the transfer. There is no standardized interpretation for the value of the field. Maximum length:20
characters.
CIE
: This field may contain the Biller's name.
CTX
: The Originator's bank account number may be placed in this field.
company_entry_description
string
Optional
You can use this optional field to provide the Receiver with a description of the purpose of the transfer. For example, “Gas bill”, “Reg. Salary”, “ins. prem.”, “Soc. Sec.”, “DTC”, “Trade Pay”, “PURCHASE”, etc.
Default value: "PAYMENT". Maximum length: 10 characters.
Characters are validated according to the ACH Valid Character Specification.company_name
string
Optional
This optional field identifies the source of the transfer and is used for descriptive purposes for the Receiver. Except as otherwise noted below, this field must contain the name by which the Originator is known to and readily recognized by the Receiver of the transfer to reduce risk of return by the Receiver
CCD
: For a Health Care EFT Transaction, this field must contain the name of the Health Plan, or where an organization is self-insured, the name of the organization's third-party administrator that is recognized by the Health Care Provider and to which the Health Care Provider submits its claims.
CIE
: This field contains the bill payment service provider's name.
WEB
: For a P2P transfer, this field contains the P2P service provider's name.
Default value: the root entity name of your platform, or "COLUMN NA" if no root entity exists. Maximum length: 16 characters.
Characters are validated according to the ACH Valid Character Specification.payment_related_info
string
Optional
Provides an additional 80 characters to give details on the ACH transaction for outgoing transfers. This information will be surfaced to the RDFI. This information will be surfaced to the RDFI. Characters are validated according to the ACH Valid Character Specification.
receiver_name
string
Optional
The name of the receiver, usually the name on the bank account of the Receiver.
Default value: beneficiary name of the counterparty. Maximum length: 22
characters.
receiver_id
string
Optional
This field contains the accounting reference number by which the Receiver is known to the Originator. It is included for further identification and for descriptive purposes.
For example, it may be the number shown on an invoice, statement, billhead, notice, or other communication as the reference for the Receiver to update account receivable records.
Maximum length: 15
characters.
entry_class_code
string
Required
Standard Entry Class code of the transfer. Valid values: CCD
, CTX
, CIE
, PPD
(default), TEL
, WEB
. More Details Here.
allow_overdraft
boolean
Optional
Allow the account to go negative for the transfer. The bank account needs to have is_overdraftable
enabled with an overdraft reserve account linked to it.
ultimate_beneficiary_counterparty
object
Optional
Counterparty object to create a counterparty an ultimate beneficiary counterparty at the time of transfer creation. This is only required on outgoing IAT debits. Either ultimate_beneficiary_counterparty
or ultimate_beneficiary_counterpartyid
is required.
ultimate_beneficiary_counterparty_id
string
Optional
ID of the ultimate beneficiary counterparty that will receive the transfer. This is only required on outgoing IAT debits. Either ultimate_beneficiary_counterparty
or ultimate_beneficiary_counterpartyid
is required.
ultimate_originator_counterparty
object
Optional
Counterparty object to create an ultimate originator counterparty at the time of transfer creation. This is only required on outgoing IAT credits. Either ultimate_originator_counterparty
or ultimate_originator_counterpartyid
is required.
ultimate_originator_counterparty_id
string
Optional
ID of the ultimate originating counterparty that will sent the transfer. This is only required on outgoing IAT credits. Either ultimate_originator_counterparty
or ultimate_originator_counterpartyid
is required.
Request
curl 'https://api.column.com/transfers/ach' \
-XPOST \
-u :<YOUR API KEY> \
-d amount=100000 \
-d currency_code="USD" \
-d bank_account_id="<bank_account_id>" \
-d counterparty_id="<counterparty_id>" \
-d type="CREDIT"
Response
{
"id": "acht_2HKbYE2th2sFioBxrRFOZL3IHR4",
"iat": null,
"type": "CREDIT",
"amount": 100000,
"status": "SUBMITTED",
"is_on_us": false,
"same_day": false,
"company_id": "9959349647",
"created_at": "2022-11-09T23:32:47Z",
"settled_at": null,
"updated_at": "2022-11-09T23:32:48Z",
"description": "",
"is_incoming": false,
"receiver_id": "",
"returned_at": null,
"cancelled_at": null,
"company_name": "COLUMN NA",
"completed_at": null,
"effective_on": "2022-11-10T08:00:00Z",
"initiated_at": "2022-11-09T23:32:47Z",
"nsf_deadline": null,
"submitted_at": "2022-11-09T23:32:48Z",
"trace_number": "121145300000005",
"currency_code": "USD",
"receiver_name": "CHASE ACCOUNT",
"return_details": [],
"acknowledged_at": null,
"allow_overdraft": false,
"bank_account_id": "bacc_2HKbY4W10hcBQBx5r42xMDEhv2K",
"counterparty_id": "cpty_2HKbYBePtS8z3zK32QvwKlIoIeK",
"idempotency_key": "",
"entry_class_code": "PPD",
"manual_review_at": null,
"account_number_id": "acno_2HKbY3eq0gPP1WaQLZShDk87JC4",
"funds_availability": "default",
"odfi_routing_number": "121145307",
"return_contested_at": null,
"payment_related_info": "payment addenda for COR testing",
"return_dishonored_at": null,
"return_dishonored_funds_unlocked_at": null,
"notification_of_changes": null,
"company_entry_description": "PAYMENT",
"reversal_pair_transfer_id": "",
"company_discretionary_data": "",
"ultimate_beneficiary_counterparty_id": "",
"ultimate_originator_counterparty_id": ""
}
List all ACH transfers
GET
/transfers/ach
Retrieve all ACH transfers under your developer account. Filtered results can be retrieved with extra parameters in the query (bank_account_id
, counterparty_id
, etc.).
query parameters
limit
int32
Optional
A limit of the number of objects to be returned, between 1
and 100
. The default is 10
.
starting_after
string
Optional
A cursor for use in pagination. starting_after
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with foo_ZXhhbXBsZQo
, your subsequent call can include starting_after=foo_ZXhhbXBsZQo
in order to fetch the next page of the list.
ending_before
string
Optional
A cursor for use in pagination. ending_before
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, starting with foo_ZXhhbXBsZQo=
, your subsequent call can include ending_before=foo_ZXhhbXBsZQo=
in order to fetch the previous page of the list.
created.gt
date-time
Optional
Return results where the specified time field is greater than this value.
created.gte
date-time
Optional
Return results where the specified time field is greater than or equal to this value.
created.lt
date-time
Optional
Return results where the specified time field is less than this value.
created.lte
date-time
Optional
Return results where the specified time field is less than or equal to this value.
bank_account_id
string
Optional
counterparty_id
string
Optional
status
string
Optional
Return results with this status.
Possible enum values:
- INITIATED
: the outgoing transfer has been initiated but not submitted yet.
-PENDING_SUBMISSION
: the outgoing transfer is to be submitted very soon.
- SUBMITTED
: the outgoing transfer has been submitted to the FRB.
- ACKNOWLEDGED
: the outgoing CCD/CTX transfer has been acknowledged by the RDFI.
- SETTLED
: the transfer has been settled.
- RETURNED
: the transfer has been returned. Please use the [ACH Return API](/docs/api/#ach-return/get) to check return details.
- COMPLETED
: the transfer has been completed, and no return (except R06 and \`R31\`) is acceptable.
- CANCELED
: the outgoing transfer has been cancelled by your request via our ACH Return API.
- SCHEDULED
: the incoming transfer has been scheduled to be settled on its Settlement Date
- PENDING_RETURN
: the incoming transfer will be returned shortly if no action is taken before the deadline
- RETURN_DISHONORED
: the return of the transfer has been dishonored by the ODFI. Please use the ACH Return API to check return details.
- RETURN_DISHONORED_FUNDS_UNLOCKED
: locked funds for the dishonored return transfer have been unlocked.
- RETURN_CONTESTED
: the dishonored return of the transfer has been contested by the RDFI. Please use the ACH Return API to check return details.
- MANUAL_REVIEW
: the transfer is under manual review.
is_incoming
boolean
Optional
Return transfers that is either incoming or outgoing.
type
string
Optional
Return transfers that are either CREDIT
or DEBIT
.
Request
curl 'https://api.column.com/transfers/ach' \
-u :<YOUR API KEY>
Response
{
"transfers": [
{
"id": "acht_28LtyrWQ7d5CZTXOjKEwVJrnlTa",
"created_at": "2022-04-26T21:19:11Z",
"updated_at": "2022-04-26T21:19:11Z",
"submitted_at": null,
"acknowledged_at": null,
"settled_at": null,
"completed_at": null,
"returned_at": null,
"cancelled_at": null,
"initiated_at": null,
"manual_review_at": null,
"return_dishonored_at": null,
"return_contested_at": null,
"status": "SCHEDULED",
"type": "DEBIT",
"idempotency_key": "",
"bank_account_id": "bacc_28Ltym2THRHbemnnJBVTH3m39fE",
"account_number_id": "acno_28LtynFqAR4JbLXYVdfwU53AVcO",
"counterparty_id": "",
"amount": 10000,
"currency_code": "USD",
"description": "received MOCK IAT transfer (trace #: 322271620000001)",
"effective_on": "2022-04-26T07:00:00Z",
"same_day": false,
"company_discretionary_data": "",
"company_entry_description": "MOCK IAT",
"company_id": "123456666",
"company_name": "STARK INDUSTRIES",
"receiver_name": "John P. Doe",
"receiver_id": "ACCT223457",
"entry_class_code": "IAT",
"allow_overdraft": false,
"is_incoming": true,
"nsf_deadline": null,
"trace_number": "322271620000001",
"odfi_routing_number": "322271627",
"return_details": [],
"is_on_us": false,
"iat": {
"foreign_payment_amount": "0",
"foreign_trace_number": "",
"receiving_company_or_individual_name": "John P. Doe",
"originator_name": "Stark Industries",
"originator_street_address": "THE WALBROOK BUILDING",
"originator_city_state_province": "LONDON*GB",
"originator_country_postal_code": "GB*EC4N 8AF",
"odfi_name": "CITIBANK EUROPE PLC",
"odfi_identification_number_qualifier": "01",
"odfi_identification": "0280008",
"odfi_branch_country_code": "IE",
"rdfi_name": "COLUMN N.A.",
"rdfi_identification_number_qualifier": "01",
"rdfi_identification": "121145307",
"rdfi_branch_country_code": "US",
"receiver_identification_number": "ACCT223457",
"receiver_street_address": "3744NBIRMINGHAMAVE",
"receiver_city_state_province": "x",
"receiver_country_postal_code": "US*74110",
"foreign_correspondent_bank_info": [],
"payment_related_info": ["1d46a25a-508e-4bc1-8a6e-5355b1dfd7aLuckyLand - 1d46a25a-508e-4bc1-8a6e"],
"transaction_type_code": "DEP"
},
"notification_of_changes": null,
"payment_related_info": "",
"reversal_pair_transfer_id": "",
"ultimate_beneficiary_counterparty_id":"",
"ultimate_originator_counterparty_id":""
},
{
"id": "acht_2HKbYE2th2sFioBxrRFOZL3IHR4",
"iat": null,
"type": "CREDIT",
"amount": 60000,
"status": "SUBMITTED",
"is_on_us": false,
"same_day": false,
"company_id": "9959349647",
"created_at": "2022-11-09T23:32:47Z",
"settled_at": null,
"updated_at": "2022-11-09T23:32:48Z",
"description": "",
"is_incoming": false,
"receiver_id": "",
"returned_at": null,
"cancelled_at": null,
"company_name": "COLUMN NA",
"completed_at": null,
"effective_on": "2022-11-10T08:00:00Z",
"initiated_at": "2022-11-09T23:32:47Z",
"nsf_deadline": null,
"submitted_at": "2022-11-09T23:32:48Z",
"trace_number": "121145300000005",
"currency_code": "USD",
"receiver_name": "CHASE ACCOUNT",
"return_details": [],
"acknowledged_at": null,
"allow_overdraft": false,
"bank_account_id": "bacc_2HKbY4W10hcBQBx5r42xMDEhv2K",
"counterparty_id": "cpty_2HKbYBePtS8z3zK32QvwKlIoIeK",
"idempotency_key": "",
"entry_class_code": "PPD",
"manual_review_at": null,
"account_number_id": "acno_2HKbY3eq0gPP1WaQLZShDk87JC4",
"funds_availability": "default",
"odfi_routing_number": "121145307",
"return_contested_at": null,
"payment_related_info": "payment addenda for COR testing",
"return_dishonored_at": null,
"notification_of_changes": null,
"company_entry_description": "PAYMENT",
"reversal_pair_transfer_id": "",
"company_discretionary_data": "",
"ultimate_beneficiary_counterparty_id":"",
"ultimate_originator_counterparty_id":""
}
],
"has_more": false
}
Get an ACH transfer
GET
/transfers/ach/<ach_transfer_id>
Retrieves a single transfer by its ID.
path parameters
ach_transfer_id
string
Required
Request
curl 'https://api.column.com/transfers/ach/<ach_transfer_id>' \
-u :<YOUR API KEY>
Response
{
"id": "acht_28LtyrWQ7d5CZTXOjKEwVJrnlTa",
"created_at": "2022-04-26T21:19:11Z",
"updated_at": "2022-04-26T21:19:11Z",
"submitted_at": null,
"acknowledged_at": null,
"settled_at": null,
"completed_at": null,
"returned_at": null,
"cancelled_at": null,
"initiated_at": null,
"manual_review_at": null,
"return_dishonored_at": null,
"return_dishonored_funds_unlocked_at": null,
"return_contested_at": null,
"status": "SCHEDULED",
"type": "DEBIT",
"idempotency_key": "",
"bank_account_id": "bacc_28Ltym2THRHbemnnJBVTH3m39fE",
"account_number_id": "acno_28LtynFqAR4JbLXYVdfwU53AVcO",
"counterparty_id": "",
"amount": 10000,
"currency_code": "USD",
"description": "received MOCK IAT transfer (trace #: 322271620000001)",
"effective_on": "2022-04-26T07:00:00Z",
"same_day": false,
"company_discretionary_data": "",
"company_entry_description": "MOCK IAT",
"company_id": "123456666",
"company_name": "STARK INDUSTRIES",
"receiver_name": "John P. Doe",
"receiver_id": "ACCT223457",
"entry_class_code": "IAT",
"allow_overdraft": false,
"is_incoming": true,
"nsf_deadline": null,
"trace_number": "322271620000001",
"odfi_routing_number": "322271627",
"return_details": [],
"is_on_us": false,
"iat": {
"foreign_payment_amount": "0",
"foreign_trace_number": "",
"receiving_company_or_individual_name": "John P. Doe",
"originator_name": "Stark Industries",
"originator_street_address": "THE WALBROOK BUILDING",
"originator_city_state_province": "LONDON*GB",
"originator_country_postal_code": "GB*EC4N 8AF",
"odfi_name": "CITIBANK EUROPE PLC",
"odfi_identification_number_qualifier": "01",
"odfi_identification": "0280008",
"odfi_branch_country_code": "IE",
"rdfi_name": "COLUMN N.A.",
"rdfi_identification_number_qualifier": "01",
"rdfi_identification": "121145307",
"rdfi_branch_country_code": "US",
"receiver_identification_number": "ACCT223457",
"receiver_street_address": "3744NBIRMINGHAMAVE",
"receiver_city_state_province": "x",
"receiver_country_postal_code": "US*74110",
"foreign_correspondent_bank_info": [],
"payment_related_info": ["1d46a25a-508e-4bc1-8a6e-5355b1dfd7aLuckyLand - 1d46a25a-508e-4bc1-8a6e"],
"transaction_type_code": "DEP"
},
"notification_of_changes": null,
"payment_related_info": "",
"reversal_pair_transfer_id": "",
"ultimate_beneficiary_counterparty_id":"",
"ultimate_originator_counterparty_id":""
}
Cancel an ACH transfer
POST
/transfers/ach/<ach_transfer_id>/cancel
Cancels an ACH transfer before it is sent to the Federal Reserve.
This action can be performed only if a given transfer is INITIATED
.
You can read more about ACH states here.
path parameters
ach_transfer_id
string
Required
Request
curl 'https://api.column.com/transfers/ach/<ach_transfer_id>/cancel' \
-XPOST \
-u :<YOUR API KEY>
Response
{
"id": "acht_28LtylaW2AzFlAkj1ZFyqW2m5tR",
"created_at": "2022-04-26T21:19:11Z",
"updated_at": "2022-04-26T21:19:11Z",
"submitted_at": null,
"acknowledged_at": null,
"settled_at": null,
"completed_at": null,
"returned_at": null,
"cancelled_at": "2022-04-26T21:19:11Z",
"initiated_at": "2022-04-26T21:19:11Z",
"manual_review_at": null,
"return_dishonored_at": null,
"return_contested_at": null,
"status": "CANCELED",
"type": "CREDIT",
"idempotency_key": "",
"bank_account_id": "bacc_28LtymCYuPbxZVKFqEb2LG25gtv",
"account_number_id": "acno_28LtyqzrhU5s1TGOjWqNrGNHpRp",
"counterparty_id": "cpty_28LtyqybwjOBwqcSYv1ogtffbYw",
"amount": 50000,
"currency_code": "USD",
"description": "test transfer",
"effective_on": "2022-04-27T07:00:00Z",
"same_day": false,
"company_discretionary_data": "",
"company_entry_description": "PAYMENT",
"company_id": "9121145307",
"company_name": "COLUMN NA",
"receiver_name": "CHASE ACCOUNT",
"receiver_id": "",
"entry_class_code": "PPD",
"allow_overdraft": false,
"is_incoming": false,
"nsf_deadline": null,
"trace_number": "",
"odfi_routing_number": "121145307",
"return_details": [],
"is_on_us": false,
"iat": null,
"payment_related_info": "",
"notification_of_changes": null,
"reversal_pair_transfer_id": "",
"ultimate_beneficiary_counterparty_id": "",
"ultimate_originator_counterparty_id": ""
}
Reverse an ACH transfer
POST
/transfers/ach/<ach_transfer_id>/reverse
Reverse an erroneous outgoing ACH transfer. You can read more about ACH Reversals.
path parameters
ach_transfer_id
string
Required
body parameters
reason
string
Required
Reason for the reversal transfer. Must be one of the following:
duplicated_entry
: the original transfer is a duplicated transferincorrect_amount
: the original transfer has an incorrect amountincorrect_receiver_account
: the original transfer has an incorrect receiver accountdebit_earlier_than_intended
: the original transfer is an ACH debit requested earlier than intendedcredit_later_than_intended
: the original transfer is an ACH credit requested later than intended
description
string
Optional
Description of the reversal transfer visible only in your platform. Maximum length: 255
characters.
Request
curl 'https://api.column.com/transfers/ach/<ach_transfer_id>/reverse' \
-XPOST \
-u :<YOUR API KEY> \
-d reason="duplicated_entry" \
-d description="reverse duplicated transfer"
Response
{
"account_number_id": "acno_28LvftEu6Ee31HZzMCLrjf9skqU",
"acknowledged_at": null,
"allow_overdraft": false,
"amount": 12500,
"bank_account_id": "bacc_28LvfooToT4UhrNLxoDX8EuZLeR",
"cancelled_at": null,
"company_discretionary_data": "",
"company_entry_description": "REVERSAL",
"company_id": "9121145307",
"company_name": "COLUMN NA",
"completed_at": null,
"counterparty_id": "cpty_28LvfpAkfFAO1PiSSEY8rJAOtou",
"created_at": "2022-04-26T21:33:07Z",
"currency_code": "USD",
"description": "reverse duplicated transfer",
"effective_on": "2022-04-27T07:00:00Z",
"entry_class_code": "PPD",
"iat": null,
"id": "acht_28LvftqvcJ7nE5BDOAMLzTBI8xe",
"idempotency_key": "28LvfqsLQYMMtFFaV95gDYbcfMo",
"initiated_at": "2022-04-26T21:33:07Z",
"is_incoming": false,
"is_on_us": false,
"manual_review_at": null,
"nsf_deadline": null,
"odfi_routing_number": "121145307",
"payment_related_info": "duplicated_entry",
"receiver_id": "",
"receiver_name": "CHASE ACCOUNT",
"return_contested_at": null,
"return_details": [],
"return_dishonored_at": null,
"returned_at": null,
"reversal_pair_transfer_id": "acht_28Lvftv63RqD69H9gpbF4oQ2JEW",
"same_day": false,
"settled_at": null,
"status": "INITIATED",
"submitted_at": null,
"trace_number": "",
"type": "DEBIT",
"notification_of_changes": null,
"updated_at": "2022-04-26T21:33:07Z",
"ultimate_beneficiary_counterparty_id":"",
"ultimate_originator_counterparty_id":""
}
ACH return object
The ACH return object represents the current state of a single ACH return originated by or received by Column. The ACH return object will contain all relevant information about the specific return, which are described in the parameters below. Read about more about ACH transfers here.
object parameters
ach_transfer_id
string
The id of the ACH transfer that is being returned.
created_at
string
The timestamp at which the return was created.
details
array of objects
Includes an object containing detailed information about the return.
addenda
string
Optional information provided about the ACH return.
created_at
string
The timestamp at which the ACH return is created.
description
string
Description of the ACH return.
return_code
string
Reason for the ACH return.
status
string
Status of the ACH return.
updated_at
string
The timestamp at which the ACH return is updated.
is_incoming
boolean
Indicates if the return was initiated by an RDFI (true
) or by Column (false
).
status
string
The current state of the ACH return. The possible states are INITIATED
, SENT
, DISHONORED
, CONTESTED
, COMPLETED
, and REJECTED
. See here for more information.
updated_at
string
The timestamp at which the return ACH return was updated (typically a status update).
ACH Return object
{
"ach_transfer_id": "acht_25JG4Xr0azGVzfNDMoCUjcO1YgF",
"created_at": "2022-02-19T07:20:08Z",
"details": [
{
"addenda": "ACH Returned by FakeFed",
"created_at": "2022-02-19T07:20:08Z",
"description": "Insufficient Funds (trace #: 322271620000003)",
"return_code": "R01",
"status": "INITIATED",
"updated_at": "2022-02-19T07:20:08Z"
}
],
"is_incoming": true,
"status": "INITIATED",
"updated_at": "2022-02-19T07:20:08Z"
}
Create an ACH return
POST
/transfers/ach/<ach_transfer_id>/return
Submit a request to return an incoming ACH transfer that is sent by other ODFIs (i.e. Column is the RDFI).
At most only one return request can be submitted for each incoming ACH transfer.
You can read more about ACH returns here.
path parameters
ach_transfer_id
string
Required
ID of the ACH transfer you intend to return.
body parameters
return_code
string
Required
Return reason codes of the return
You can read more about ACH return reason codes here.
description
string
Optional
Description of the reason for the return. Maximum length: 255 characters. This is for internal use only and will not be transmitted to the ODFI.
addenda
string
Optional
If provided, this string will be sent as the addenda information field of the ACH addenda entry to the ODFI. Maximum length: 44 characters.
Request
curl 'https://api.column.com/transfers/ach/<ach_transfer_id>/return' \
-XPOST \
-u :<YOUR API KEY> \
-d return_code="R10"
Response
{
"ach_transfer_id": "string",
"created_at": "2021-11-29T20:08:58.662Z",
"updated_at": "2021-11-29T20:08:58.662Z",
"status": "INVALID",
"is_incoming": true,
"details": [
{
"created_at": "2021-11-29T20:08:58.662Z",
"updated_at": "2021-11-29T20:08:58.662Z",
"status": "INVALID",
"return_code": "string",
"description": "string",
"addenda": "string"
}
]
}
List all ACH returns
GET
/transfers/ach/returns
Retrieve the return processing details of all ACH transfers under your developer account, including both returns filed by your platform and returns sent by other RDFIs.
query parameters
limit
int32
Optional
A limit of the number of objects to be returned, between 1
and 100
. The default is 10
.
starting_after
string
Optional
A cursor for use in pagination. starting_after
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with foo_ZXhhbXBsZQo
, your subsequent call can include starting_after=foo_ZXhhbXBsZQo
in order to fetch the next page of the list.
ending_before
string
Optional
A cursor for use in pagination. ending_before
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, starting with foo_ZXhhbXBsZQo=
, your subsequent call can include ending_before=foo_ZXhhbXBsZQo=
in order to fetch the previous page of the list.
created.gt
date-time
Optional
Return results where the specified time field is greater than this value.
created.gte
date-time
Optional
Return results where the specified time field is greater than or equal to this value.
created.lt
date-time
Optional
Return results where the specified time field is less than this value.
created.lte
date-time
Optional
Return results where the specified time field is less than or equal to this value.
Request
curl 'https://api.column.com/transfers/ach/returns' \
-u :<YOUR API KEY>
Response
{
"ach_returns": [
{
"ach_transfer_id": "string",
"created_at": "2021-11-29T20:00:20.304Z",
"updated_at": "2021-11-29T20:00:20.304Z",
"status": "INVALID",
"is_incoming": true,
"details": [
{
"created_at": "2021-11-29T20:00:20.304Z",
"updated_at": "2021-11-29T20:00:20.304Z",
"status": "INVALID",
"return_code": "string",
"description": "string",
"addenda": "string"
}
]
}
],
"has_more": true
}
Get an ACH return
GET
/transfers/ach/<ach_transfer_id>/return
Retrieve the return processing details of an ACH transfer. The return may be either filed by your platform, or sent to you by other RDFIs.
path parameters
ach_transfer_id
string
Required
ID of the ACH transfer you're looking up.
Request
curl 'https://api.column.com/transfers/ach/<ach_transfer_id>/return' \
-u :<YOUR API KEY>
Response
{
"ach_transfer_id": "string",
"created_at": "2021-11-29T20:08:18.295Z",
"updated_at": "2021-11-29T20:08:18.295Z",
"status": "INVALID",
"is_incoming": true,
"details": [
{
"created_at": "2021-11-29T20:08:18.295Z",
"updated_at": "2021-11-29T20:08:18.295Z",
"status": "INVALID",
"return_code": "string",
"description": "string",
"addenda": "string"
}
]
}
Book transfer object
The book transfer object is the current state of a single book transfer initiated in Column. A book transfer is the movement of funds between two bank accounts under your platform, and once initiated, happen instantaneously 24/7. Read about more about book transfers here.
object parameters
allow_overdraft
boolean
Allows the account to go negative for an outgoing transfer. The bank account needs to haveis_overdraftable
enabled with an overdraft reserve account linked to it
amount
int64
Amount (in cents) of the funds that will be transferred between sender and receiver accounts.
e.g. $1.75 would be represented by 175
created_at
string
The timestamp at which the transfer request is created.
currency_code
string
The three-letter currency code defined in ISO 4217. e.g. USD
description
string
A description of the transfer visible in people's accounts.
id
string
The unique id of the object.
idempotency_key
string
The idempotency key specified in the book transfer.
receiver_account_number_id
string
ID of the account number that will receive the transfer.
receiver_bank_account_id
string
ID of the bank account that will receive the transfer.
sender_account_number_id
string
ID of the account number that is sending the transfer.
sender_bank_account_id
string
ID of the bank account that is sending the transfer.
status
string
The current status of the book transfer. Possible values: REJECTED
, COMPLETED
, HOLD
, and CANCELED
.
updated_at
string
The timestamp at which the book transfer was updated (typically a status update).
Book Transfer object
{
"allow_overdraft": false,
"amount": 50000,
"created_at": "2022-03-02T22:44:35Z",
"currency_code": "USD",
"description": "For documents",
"id": "book_25qiZnUKr2AP8Rb5Vs3PGzpcttC",
"idempotency_key": "",
"receiver_account_number_id": "acno_25FyF49P2SE4PJJOmfx6kYCzkeI",
"receiver_bank_account_id": "bacc_25FyEyuKX3KlRAciUs3BzXag1RI",
"sender_account_number_id": "acno_25nVQkqfCU6Okpn66QWi1xX9riD",
"sender_bank_account_id": "bacc_25nVQr05nZybpyEzw8j0wV6VRUh",
"status": "COMPLETED",
"updated_at": "2022-03-02T22:44:35Z"
}
Create a book transfer
POST
/transfers/book
A book transfer, is a transaction between between two Column accounts that you own.
They can happen instantly and can be sent 24 hours a day, 7 days a week. Both accounts need to under your platform, but don't need to be under the same entity.
Alternatively, you can send a book transfer in two steps, using the "hold" parameter and "clear" method. Book transfers in a "hold" state can be updated and canceled.
There is no reversal functionality for book transfers. Simply swap the originator_account_number_id
and receiver_account_number_id
and repeat the request.
body parameters
description
string
Optional
A description of the transfer visible in people's accounts.
amount
int64
Required
Amount (in cents) of the funds that will be transferred between sender and receiver accounts.
e.g. $1.75 would be represented by 175
currency_code
string
Required
The three-letter currency code defined in ISO 4217. e.g. USD
sender_bank_account_id
string
Optional
ID of the bank account that is sending the transfer. If no sender_account_number_id
is specified, the default account number on sender_bank_account_id
is used.
sender_bank_account_id
or sender_account_number_id
is required
sender_account_number_id
string
Optional
ID of the account number that is sending the transfer.
If this is specified, the sender_bank_account_id
does not need to be included.
sender_bank_account_id
or sender_account_number_id
is required
receiver_bank_account_id
string
Optional
ID of the bank account that will receive the transfer. If no receiver_account_number_id
is specified, the default account number on receiver_bank_account_id
is used.
receiver_bank_account_id
or receiver_account_number_id
is required
receiver_account_number_id
string
Optional
ID of the account number that will receive the transfer. If this is specified, the receiver_bank_account_id
does not need to be included.
receiver_bank_account_id
or receiver_account_number_id
is required
allow_overdraft
boolean
Optional
Allows the account to go negative for an outgoing transfer. The bank account needs to haveis_overdraftable
enabled with an overdraft reserve account linked to it
hold
boolean
Optional
Creates a book transfer in a hold
state. The transfer will not be completed until the clear
API is called. Transfers in a hold
state may be updated or canceled.
details
object
Optional
Transfer monitoring details
sender_name
string
Optional
Name of the sender
merchant_name
string
Optional
Name of the merchant for this transaction
merchant_category_code
string
Optional
Category code for the merchant for this transaction
authorization_method
string
Optional
Authorization method for this transaction
website
string
Optional
Website for this transaction
internal_transfer_type
string
Optional
Transfer type in non-column systems
statement_description
string
Optional
Line item on the customer statement for the transfer
address
object
Required
Addresses need to adhere to character validation, as addresses are used across multiple payment rails. Characters are validated according to the ACH Valid Character Specification.
line_1
string
Required
Address line 1
line_2
string
Optional
Address line 2
city
string
Required
City
state
string
Optional
State name. For US addresses, this field is mandatory and only postal abbreviations (e.g. AL, CA, DE, ...
) are allowed.
postal_code
string
Optional
Postal code
country_code
string
Required
ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
).
Request
curl 'https://api.column.com/transfers/book' \
-XPOST \
-u :<YOUR API KEY> \
-d amount=10000 \
-d currency_code="USD" \
-d sender_bank_account_id="<bank_account_id>" \
-d receiver_bank_account_id="<bank_account_id>"
Response
{
"id": "string",
"created_at": "2021-11-29T20:18:34.844Z",
"updated_at": "2021-11-29T20:18:34.844Z",
"idempotency_key": "string",
"sender_bank_account_id": "string",
"sender_account_number_id": "string",
"receiver_bank_account_id": "string",
"receiver_account_number_id": "string",
"amount": int64,
"currency_code": "string",
"description": "string",
"status": "NONE",
"allow_overdraft": true,
"details": {}
}
List all book transfers
GET
/transfers/book
Retrieve all book transfers under your developer account. Filtered results can be retrieved with extra parameters in the query (sender_bank_account_id
, receiver_bank_account_id
, etc.).
query parameters
limit
int32
Optional
A limit of the number of objects to be returned, between 1
and 100
. The default is 10
.
starting_after
string
Optional
A cursor for use in pagination. starting_after
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with foo_ZXhhbXBsZQo
, your subsequent call can include starting_after=foo_ZXhhbXBsZQo
in order to fetch the next page of the list.
ending_before
string
Optional
A cursor for use in pagination. ending_before
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, starting with foo_ZXhhbXBsZQo=
, your subsequent call can include ending_before=foo_ZXhhbXBsZQo=
in order to fetch the previous page of the list.
created.gt
date-time
Optional
Return results where the specified time field is greater than this value.
created.gte
date-time
Optional
Return results where the specified time field is greater than or equal to this value.
created.lt
date-time
Optional
Return results where the specified time field is less than this value.
created.lte
date-time
Optional
Return results where the specified time field is less than or equal to this value.
sender_bank_account_id
string
Optional
Return results associated with this sender bank account.
receiver_bank_account_id
string
Optional
Return results associated with this receiver bank account.
status
string
Optional
Return results with this status.
Possible enum values:
REJECTED
COMPLETED
HOLD
CANCELED
Request
curl 'https://api.column.com/transfers/book' \
-u :<YOUR API KEY>
Response
{
"transfers": [
{
"id": "string",
"created_at": "2021-11-29T20:22:11.956Z",
"updated_at": "2021-11-29T20:22:11.956Z",
"idempotency_key": "string",
"sender_bank_account_id": "string",
"sender_account_number_id": "string",
"receiver_bank_account_id": "string",
"receiver_account_number_id": "string",
"amount": int64,
"currency_code": "string",
"description": "string",
"status": "NONE",
"allow_overdraft": true
}
],
"has_more": true
}
Get a book transfer
GET
/transfers/book/<book_transfer_id>
Retrieve a single book transfer by its ID
path parameters
book_transfer_id
string
Required
ID of the book transfer you're looking up.
Request
curl 'https://api.column.com/transfers/book/<book_transfer_id>' \
-u :<YOUR API KEY>
Response
{
"id": "string",
"created_at": "2021-11-29T20:22:41.596Z",
"updated_at": "2021-11-29T20:22:41.596Z",
"idempotency_key": "string",
"sender_bank_account_id": "string",
"sender_account_number_id": "string",
"receiver_bank_account_id": "string",
"receiver_account_number_id": "string",
"amount": int64,
"currency_code": "string",
"description": "string",
"status": "NONE",
"allow_overdraft": true
}
Update a book transfer
PATCH
/transfers/book/<book_transfer_id>
Update a book transfer by its ID. Transfer must be in a "hold" state. Only the amount
can be updated.
path parameters
book_transfer_id
string
Required
body parameters
amount
int64
Required
Amount (in cents) to update the hold to. Can be lower or higher than the original amount. This will not clear the hold.
e.g. $1.75 would be represented by 175
currency_code
string
Required
The three-letter currency code defined in ISO 4217. e.g. USD
allow_overdraft
boolean
Optional
If true, will cause the hold to overdraft the available balance if the amount is greater than the available balance.
Request
curl 'https://api.column.com/transfers/book/<book_transfer_id>' \
-XPATCH \
-u :<YOUR API KEY> \
-d amount=15000 \
-d currency_code="USD"
Response
{
"id": "string",
"created_at": "2021-11-29T20:22:41.596Z",
"updated_at": "2021-11-29T20:22:41.596Z",
"idempotency_key": "string",
"sender_bank_account_id": "string",
"sender_account_number_id": "string",
"receiver_bank_account_id": "string",
"receiver_account_number_id": "string",
"amount": int64,
"currency_code": "string",
"description": "string",
"status": "NONE",
"allow_overdraft": true
}
Cancel a book transfer
POST
/transfers/book/<book_transfer_id>/cancel
Cancel a book transfer hold by its ID. Transfer must be in a "hold" state.
path parameters
book_transfer_id
string
Required
Request
curl 'https://api.column.com/transfers/book/<book_transfer_id>/cancel' \
-XPOST \
-u :<YOUR API KEY>
Response
{
"id": "string",
"created_at": "2021-11-29T20:24:42.867Z",
"updated_at": "2021-11-29T20:24:42.867Z",
"idempotency_key": "string",
"sender_bank_account_id": "string",
"sender_account_number_id": "string",
"receiver_bank_account_id": "string",
"receiver_account_number_id": "string",
"amount": int64,
"currency_code": "string",
"description": "string",
"status": "NONE",
"allow_overdraft": true
}
Clear a book transfer
POST
/transfers/book/<book_transfer_id>/clear
Clear a book transfer by its ID. Transfer must be in a "hold" state. If the amount
is specified, then that amount will be cleared, regardless of the amount of the hold. If no amount is specified, then the amount of the hold will be cleared.
path parameters
book_transfer_id
string
Required
body parameters
amount
int64
Optional
Amount (in cents) to clear the hold to. Can be lower or higher than the original amount. If no amount is specified, the hold will be cleared for the original amount on the transfer.
currency_code
string
Optional
The three-letter currency code defined in ISO 4217. e.g. USD
allow_overdraft
boolean
Optional
If true, will cause the clear to overdraft the available balance if the amount is greater than the available balance.
Request
curl 'https://api.column.com/transfers/book/<book_transfer_id>/clear' \
-u :<YOUR API KEY> \
-d amount=150000 \
-d currency_code="USD"
Response
{
"id": "string",
"created_at": "2021-11-29T20:24:42.867Z",
"updated_at": "2021-11-29T20:24:42.867Z",
"idempotency_key": "string",
"sender_bank_account_id": "string",
"sender_account_number_id": "string",
"receiver_bank_account_id": "string",
"receiver_account_number_id": "string",
"amount": int64,
"currency_code": "string",
"description": "string",
"status": "NONE",
"allow_overdraft": true
}
Wire transfer object
The wire transfer object represents the current state of a single wire transfer initiated by or received by Column. Wire transfers are used to send and receive money over Fedwire. The wire transfer object exposes all relevant information about the wire transfer to developers. Read about more about wire transfers here.
object parameters
account_number_id
string
ID of the account number that is sending/receiving the transfer.
allow_overdraft
bool
Allows the account to go negative for an outgoing transfer. The bank account needs to haveis_overdraftable
enabled with an overdraft reserve account linked to it
amount
integer
Amount (in cents) of the funds that will be transferred between originator and counterparty accounts.
e.g. $1.75 would be represented by 175
bank_account_id
string
ID of the bank number that is sending/receiving the transfer.
beneficiary_account_number
string
The external account number to which the wire is being sent.
beneficiary_name
string
The name of the person who is receiving the wire.
business_function_code
string
The business function code specified in the wire transfer. Possible business function codes are BTR
, CTP
, CTR
, DRC
, or DRW
.
completed_at
string
The timestamp when the wire was completed.
counterparty_id
string
ID of the counterparty
that is receiving/sending the transfer
created_at
string
The timestamp when the wire was created.
currency_code
string
The three-letter currency code defined in ISO 4217. e.g. USD
description
string
A description of the transfer visible in people's accounts.
fi_to_fi_information_line_<1-6>
string
Financial institution to financial institution information, most often used by a FI to explain the reason for a wire reversal. Column will populate this for outgoing reversals. There can be up to six separate parameters, one for each message line.
id
string
The unique id of the object.
idempotency_key
string
The idempotency key specified in the wire transfer.
imad
string
Stands for Input/Output Message Accountability Data. A unique number set by the originating bank given to each FedWire payment when using the Federal Reserve Bank Service and can be used to investigate and track wire transfers. IMAD will be populated asynchronously and will not be populated on the completed
event. IMAD will also not be populated for on-us wire transfers.
initiated_at
string
The timestamp when the wire was initiated.
is_incoming
boolean
Indicates whether the wire transfer was incoming (true
or outgoing false
)
is_on_us
boolean
Indicates whether the wire transfer was between two bank accounts held at Column.
manual_review_at
string
The timestamp when the wire went into the manual review state.
omad
string
Stands for Input/Output Message Accountability Data. A unique number set by the Fed given to each FedWire payment when using the Federal Reserve Bank Service and can be used to investigate and track wire transfers. OMAD will be populated asynchronously and will not be populated on the completed
event. OMAD will also not be populated for on-us wire transfers.
originator_account_number
string
The external account number from which the wire is originated.
originator_name
string
The name of the person or entity that is originating the wire.
pending_submission_at
string
The timestamp when the wire was marked PENDING_SUBMISSION
.
previous_message_reference
string
The previous message identifier included in the raw wire message.
raw_beneficiary_address
string
The unstructured beneficiary address extracted from the raw wire message.
raw_originator_address
string
The unstructured originator address extracted from the raw wire message
receiver_di_name
string
The name of the person / entity that received the wire.
receiver_di_routing_number
string
The routing number of the bank that received the wire.
rejected_at
string
The timestamp when the wire was rejected.
reversal_pair_transfer_id
string
If the transfer is the original transfer of an wire reversal, this field is the unique ID of the reversal transfer. If the transfer is the reversal transfer of a wire reversal, this field is the unique ID of the original transfer. Please refer to Wire Reversals for more details.
sender_di_name
string
The name of the person / entity that sent the wire.
sender_di_routing_number
string
The routing number of the bank that sent the wire.
sender_reference
string
The sender reference field parsed out from the raw wire message.
status
string
The current status of the wire transfer. Possible statuses are INITIATED
, COMPLETED
, REJECTED
, and MANUAL_REVIEW
.
submitted_at
string
The timestamp when the wire was submitted.
subtype_code
string
The subtype code specified in the wire transfer.
type_code
string
The type code specified in the wire transfer.
updated_at
string
The timestamp when the wire was updated.
wire_drawdown_request_id
string
ID of the wire drawdown request if the wire is sent in response to a wire drawdown request.
Wire Transfer Object
{
"account_number_id": "acno_25nacNsLD8qLI1Vc6x67sxFU27c",
"allow_overdraft": false,
"amount": 100000,
"bank_account_id": "bacc_25nVQr05nZybpyEzw8j0wV6VRUh",
"beneficiary_account_number": "256783259046169",
"beneficiary_name": "Column account",
"business_function_code": "CTR"
"completed_at": "2022-03-02T00:05:54Z",
"counterparty_id": "cpty_25QihOzMbXhGQVNHQmeIp6UJNnj",
"created_at": "2022-03-02T00:05:54Z",
"currency_code": "USD",
"description": "incoming CTR wire transfer",
"fi_to_fi_information_line_1": "",
"fi_to_fi_information_line_2": "",
"fi_to_fi_information_line_3": "",
"fi_to_fi_information_line_4": "",
"fi_to_fi_information_line_5": "",
"fi_to_fi_information_line_6": "",
"id": "wire_25o3LGGbxLjpabTm6zHquAM1ti2",
"idempotency_key": "",
"imad": "20220301CHASE001000001",
"initiated_at": "2022-03-02T00:05:54Z",
"is_incoming": true,
"is_on_us": false,
"manual_review_at": null,
"omad": "20220301MMQFMC2U000001",
"originator_account_number": "1234567890",
"originator_name": "Chase account",
"pending_submission_at": null,
"previous_message_reference": "",
"raw_beneficiary_address": "",
"raw_originator_address": "",
"receiver_di_name": "Column Bank",
"receiver_di_routing_number": "091000019",
"rejected_at": null,
"reversal_pair_transfer_id": null,
"sender_di_name": "TestBank",
"sender_di_routing_number": "322271627",
"sender_reference": "",
"status": "COMPLETED",
"submitted_at": null,
"subtype_code": "00",
"type_code": "10",
"updated_at": "2022-03-02T00:05:54Z",
"wire_drawdown_request_id":"",
}
Create a wire transfer
POST
/transfers/wire
Create a wire transfer between a Column account and a counterparty.
body parameters
description
string
Optional
A description of the transfer visible in people's accounts. This field will be transmitted to the RDFI and is often visible in the beneficiary's statement. Must adhere to Fedwire character validation.
amount
int64
Required
Amount (in cents) of the funds that will be transferred between originator and counterparty accounts.
e.g. $1.75 would be represented by 175
currency_code
string
Required
The three-letter currency code defined in ISO 4217. e.g. USD
account_number_id
string
Optional
ID of the account number that is sending the transfer. If this is specified, the bank_account_id
does not need to be included.
account_number_id
or bank_account_id
is required
bank_account_id
string
Optional
ID of the bank number that is sending the transfer. If no account_number_id
is specified, the default account number on bank_account_id
is used.
account_number_id
or bank_account_id
is required
counterparty_id
string
Required
ID of the counterparty
that will receive the transfer
Note: A wire object must be attached to the counterparty
. If it is not, this request will fail.
allow_overdraft
boolean
Optional
Allows the account to go negative for an outgoing transfer. The bank account needs to haveis_overdraftable
enabled with an overdraft reserve account linked to it
Request
curl 'https://api.column.com/transfers/wire' \
-XPOST \
-u :<YOUR API KEY> \
-d description="Example wire transfer" \
-d amount=10000 \
-d currency_code="USD" \
-d bank_account_id="<bank_account_id>" \
-d counterparty_id="<counterparty_id>"
Response
{
"id": "wire_2DucXfsrbVzW4GsNMUmFum1eOeP",
"created_at": "2021-11-29T20:40:19.916Z",
"updated_at": "2021-11-29T20:40:19.916Z",
"initiated_at": "2021-11-29T20:40:19.916Z",
"pending_submission_at": "2021-11-29T20:40:19.916Z",
"submitted_at": "2021-11-29T20:40:19.916Z",
"completed_at": "2021-11-29T20:40:19.916Z",
"rejected_at": "2021-11-29T20:40:19.916Z",
"idempotency_key": "string",
"bank_account_id": "string",
"account_number_id": "string",
"counterparty_id": "string",
"amount": int64,
"currency_code": "string",
"description": "string",
"status": "NONE",
"allow_overdraft": true,
"platform_id": "string",
"is_on_us": true,
"is_incoming": true,
"wire_drawdown_request_id":"",
}
List all wire transfers
GET
/transfers/wire
Retrieve all wire transfers under your platform
query parameters
limit
int32
Optional
A limit of the number of objects to be returned, between 1
and 100
. The default is 10
.
starting_after
string
Optional
A cursor for use in pagination. starting_after
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with foo_ZXhhbXBsZQo
, your subsequent call can include starting_after=foo_ZXhhbXBsZQo
in order to fetch the next page of the list.
ending_before
string
Optional
A cursor for use in pagination. ending_before
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, starting with foo_ZXhhbXBsZQo=
, your subsequent call can include ending_before=foo_ZXhhbXBsZQo=
in order to fetch the previous page of the list.
created.gt
date-time
Optional
Return results where the specified time field is greater than this value.
created.gte
date-time
Optional
Return results where the specified time field is greater than or equal to this value.
created.lt
date-time
Optional
Return results where the specified time field is less than this value.
created.lte
date-time
Optional
Return results where the specified time field is less than or equal to this value.
bank_account_id
string
Optional
Return results associated with this bank account.
counterparty_id
string
Optional
Return results associated with this counterparty.
status
string
Optional
Return results with this status.
Possible enum values:
NONE
INITIATED
PENDING_SUBMISSION
SUBMITTED
COMPLETED
REJECTED
MANUAL_REVIEW
is_incoming
boolean
Optional
Return transfers that is either incoming or outgoing.
Request
curl 'https://api.column.com/transfers/wire' \
-u :<YOUR API KEY>
Response
{
"transfers": [
{
"id": "string",
"created_at": "2021-11-29T20:43:16.326Z",
"updated_at": "2021-11-29T20:43:16.326Z",
"initiated_at": "2021-11-29T20:43:16.326Z",
"pending_submission_at": "2021-11-29T20:43:16.326Z",
"submitted_at": "2021-11-29T20:43:16.326Z",
"completed_at": "2021-11-29T20:43:16.326Z",
"rejected_at": "2021-11-29T20:43:16.326Z",
"idempotency_key": "string",
"bank_account_id": "string",
"account_number_id": "string",
"counterparty_id": "string",
"amount": int64,
"currency_code": "string",
"description": "string",
"status": "NONE",
"allow_overdraft": true,
"platform_id": "string",
"is_on_us": true,
"is_incoming": true,
"wire_drawdown_request_id":"",
}
],
"has_more": true
}
Get wire transfer
GET
/transfers/wire/<wire_transfer_id>
Retrieve a single wire transfer by its ID
path parameters
wire_transfer_id
string
Required
ID of the wire transfer you're looking up.
Request
curl 'https://api.column.com/transfers/wire/<wire_transfer_id>' \
-u :<YOUR API KEY>
Response
{
"id": "string",
"created_at": "2021-11-29T20:44:53.287Z",
"updated_at": "2021-11-29T20:44:53.287Z",
"initiated_at": "2021-11-29T20:44:53.287Z",
"pending_submission_at": "2021-11-29T20:44:53.287Z",
"submitted_at": "2021-11-29T20:44:53.287Z",
"completed_at": "2021-11-29T20:44:53.287Z",
"rejected_at": "2021-11-29T20:44:53.287Z",
"idempotency_key": "string",
"bank_account_id": "string",
"account_number_id": "string",
"counterparty_id": "string",
"amount": int64,
"currency_code": "string",
"description": "string",
"status": "NONE",
"allow_overdraft": true,
"platform_id": "string",
"is_on_us": true,
"is_incoming": true,
"wire_drawdown_request_id":"",
}
Reverse an incoming wire transfer
POST
/transfers/wire/<wire_transfer_id>/reverse
Reverse an incoming wire transfer received in error. You can read more about Wire Reversals.
path parameters
wire_transfer_id
string
Required
body parameters
reason
string
Required
Reason for the reversal transfer. Must be one of the following:
invalid_beneficiary_account_number
: the beneficiary account number is invalidbeneficiary_mismatch
: beneficiary information in the wire does not match the corresponding information on the accountbeneficiary_request
: the beneficiary is refusing the wireoriginator_request
: the beneficiary is reversing the wire as per the sender's request
description
string
Optional
Description of the reversal transfer visible only in your platform. Maximum length: 255
characters.
Request
curl 'https://api.column.com/transfers/wire/<wire_transfer_id>/reverse' \
-XPOST \
-u :<YOUR API KEY> \
-d reason="invalid_beneficiary_account_number" \
-d description="the beneficiary account number does not exist"
Response
{
"id": "wire_2DucXfsrbVzW4GsNMUmFum1eOeP",
"created_at": "2021-11-29T20:40:19.916Z",
"updated_at": "2021-11-29T20:40:19.916Z",
"initiated_at": "2021-11-29T20:40:19.916Z",
"pending_submission_at": "2021-11-29T20:40:19.916Z",
"submitted_at": "2021-11-29T20:40:19.916Z",
"completed_at": "2021-11-29T20:40:19.916Z",
"rejected_at": "2021-11-29T20:40:19.916Z",
"reversal_pair_transfer_id": "wire_2DuchZzpgT8W49QUdepFAKTQMSH",
"idempotency_key": "string",
"bank_account_id": "string",
"account_number_id": "string",
"counterparty_id": "string",
"amount": int64,
"currency_code": "string",
"description": "string",
"status": "NONE",
"allow_overdraft": true,
"platform_id": "string",
"is_on_us": false,
"is_incoming": true,
"wire_drawdown_request_id":"",
}
Wire drawdown object
The wire drawdown object represents the current state of a single wire drawdown received by Column. Wire drawdowns are used to request a customer send a wire to a verified counterparty.
object parameters
account_number_id
string
The Column account number id to which the wire drawdown request was made.
amount
int64
Amount (in cents) that will be transferred between originator and counterparty accounts if the wire drawdown is approved.
bank_account_id
string
Column bank account id to which the wire drawdown request was made.
beneficiary_account_number
string
The external account number to which funds will be sent if the wire drawdown request is approved.
beneficiary_name
string
The name of the person who will receive funds with via wire if the wire drawdown request is approved.
beneficiary_counterparty_id
string
The counterparty ID, which Column automatically creates, to which funds will be sent if the wire drawdown request is approved.
beneficiary_name
string
The beneficiary name to which funds will be sent if the wire drawdown request is approved.
currency_code
string
The three-letter currency code defined in ISO 4217. e.g. USD
id
string
The unique id of the wire drawdown request object.
imad
string
The IMAD included in the wire drawdown request. Stands for Input/Output Message Accountability Data. A unique number set by the originating bank given to each FedWire payment when using the Federal Reserve Bank Service and can be used to investigate and track wire transfers. IMAD will not be populated for on-us wire transfers.
is_incoming
boolean
Indicates whether the wire drawdown request is incoming. (true
or outgoing false
)
message_identifier
string
The message identifier supplied in the wire drawdown request. This is typically the same as the IMAD.
originator_account_number
string
The account number of the originator of the wire drawdown request. This is often different from the beneficiary account number.
originator_name
string
The name of the originator who sent the wire drawdown request. This is often different from the beneficiary name.
originator_to_beneficiary_information
string
Free form text where the originator may supply some additional information describing the wire drawdown request.
received_at
string
Date/time at which the wire drawdown request was received (UTC).
receiver_di_name
string
The name of the financial institution to which the wire drawdown request was sent.
receiver_di_routing_number
boolean
The routing number of the financial institution to which the wire drawdown request was sent.
sender_di_name
string
The name of the financial institution that sent the wire drawdown request.
sender_di_routing_number
string
The routing number of the financial institution that sent the wire drawdown request.
status
string
The status of the wire drawdown request. Possible statuses include received
, initiated
, sent
, approved
, denied
, completed
, and rejected
.
supplementary_beneficiary_counterparty_id
string
In the case you need to supplement counterparty information to approve a drawdown, create a new counterparty and pass the resulting ID here. Routing number and account number of the original drawdown request must match.
wire_transfer_id
string
The wire transfer ID of the outgoing wire transfer should a wire drawdown request be approved.
Wire Drawdown Object
{
"account_number_id": "acno_2N9g8VZKfCRXItzIV7bev39KlQ5",
"amount": 100,
"bank_account_id": "bacc_2N9g8VbA3n5NCh068GQwD5hrlS0",
"beneficiary_account_number": "403943517509507",
"beneficiary_counterparty_id": "cpty_2Jq2AyMFZhulLdrlBHcJw17SPGa",
"beneficiary_name": "Yellen Cocktails, LLC",
"currency_code": "USD",
"id": "wdrw_2N9lWiJF2bGit9RGxOuWpAfrnKP",
"imad": "20230317I1B7032R00000",
"is_incoming": true,
"message_identifier": "20230317I1B7032R00000",
"originator_account_number": "",
"originator_name": "",
"originator_to_beneficiary_information": null,
"received_at": "2023-03-17T19:06:52Z",
"receiver_di_name": "Yellen Cocktails, LLC",
"receiver_di_routing_number": "121145307",
"sender_di_name": "WELLS FARGO SF",
"sender_di_routing_number": "121000248",
"status": "received",
"supplementary_beneficiary_counterparty_id": "",
"wire_transfer_id": ""
}
Get a wire drawdown request
GET
/transfers/wire/drawdown/<wire_drawdown_request_id>
Retrieves a single wire drawdown request by its ID.
path parameters
wire_drawdown_request_id
string
Required
Request
curl 'https://api.column.com/transfers/wire/drawdown/<wire_drawdown_request_id>' \
-u :<YOUR API KEY>
Response
{
"account_number_id": "acno_2N9g8VZKfCRXItzIV7bev39KlQ5",
"amount": 100,
"bank_account_id": "bacc_2N9g8VbA3n5NCh068GQwD5hrlS0",
"beneficiary_account_number": "403943517509507",
"beneficiary_counterparty_id": "cpty_2Jq2AyMFZhulLdrlBHcJw17SPGa",
"beneficiary_name": "Yellen Cocktails, LLC",
"currency_code": "USD",
"id": "wdrw_2N9lWiJF2bGit9RGxOuWpAfrnKP",
"imad": "20230317I1B7032R00000",
"is_incoming": true,
"message_identifier": "20230317I1B7032R00000",
"originator_account_number": "",
"originator_name": "",
"originator_to_beneficiary_information": null,
"received_at": "2023-03-17T19:06:52Z",
"receiver_di_name": "Yellen Cocktails, LLC",
"receiver_di_routing_number": "121145307",
"sender_di_name": "WELLS FARGO SF",
"sender_di_routing_number": "121000248",
"status": "received",
"supplementary_beneficiary_counterparty_id": "",
"wire_transfer_id": ""
}
Approve a wire drawdown request
POST
/transfers/wire/drawdown/<wire_drawdown_request_id>/approve
Approves a single wire drawdown request by its ID. If approved, an outgoing wire is initiated using the information specified in the drawdown request.
path parameters
wire_drawdown_request_id
string
Required
body parameters
supplementary_beneficiary_counterparty_id
string
Optional
In the case you need to supplement counterparty information to approve a drawdown, create a new counterparty and pass the resulting ID here. Routing number and account number of the original drawdown request must match.
Request
curl 'https://api.column.com/transfers/wire/drawdown/<wire_drawdown_request_id>/approve' \
-X POST \
-u :<YOUR API KEY>
Response
{
"account_number_id": "acno_2N9g8VZKfCRXItzIV7bev39KlQ5",
"amount": 100,
"bank_account_id": "bacc_2N9g8VbA3n5NCh068GQwD5hrlS0",
"beneficiary_account_number": "403943517509507",
"beneficiary_counterparty_id": "cpty_2Jq2AyMFZhulLdrlBHcJw17SPGa",
"beneficiary_name": "Yellen Cocktails, LLC",
"currency_code": "USD",
"id": "wdrw_2N9lWiJF2bGit9RGxOuWpAfrnKP",
"imad": "20230317I1B7032R00000",
"is_incoming": true,
"message_identifier": "20230317I1B7032R00000",
"originator_account_number": "",
"originator_name": "",
"originator_to_beneficiary_information": null,
"received_at": "2023-03-17T19:06:52Z",
"receiver_di_name": "Yellen Cocktails, LLC",
"receiver_di_routing_number": "121145307",
"sender_di_name": "WELLS FARGO SF",
"sender_di_routing_number": "121000248",
"status": "approved",
"supplementary_beneficiary_counterparty_id": "",
"wire_transfer_id": "wire_4K8jWiJF3bGit6RHmKuJpWnjpQN"
}
List all wire drawdown requests
GET
/transfers/wire/drawdown
Retrieve all wire drawdowns under your developer account.
query parameters
limit
int32
Optional
A limit of the number of objects to be returned, between 1
and 100
. The default is 10
.
starting_after
string
Optional
A cursor for use in pagination. starting_after
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with foo_ZXhhbXBsZQo
, your subsequent call can include starting_after=foo_ZXhhbXBsZQo
in order to fetch the next page of the list.
ending_before
string
Optional
A cursor for use in pagination. ending_before
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, starting with foo_ZXhhbXBsZQo=
, your subsequent call can include ending_before=foo_ZXhhbXBsZQo=
in order to fetch the previous page of the list.
created.gt
date-time
Optional
Return results where the specified time field is greater than this value.
created.gte
date-time
Optional
Return results where the specified time field is greater than or equal to this value.
created.lt
date-time
Optional
Return results where the specified time field is less than this value.
created.lte
date-time
Optional
Return results where the specified time field is less than or equal to this value.
bank_account_id
string
Optional
Return results associated with this bank account.
account_number_id
string
Optional
Return results associated with this account number.
beneficiary_counterparty_id
string
Optional
Return results associated with this beneficiary counterparty.
status
string
Optional
Return results with this status.
Possible enum values:
received
approved
denied
completed
rejected
is_incoming
boolean
Optional
All wire drawdowns are incoming, and thus is_incoming
will be true.
Request
curl 'https://api.column.com/transfers/wire/drawdown' \
-u :<YOUR API KEY>
Response
{
"transfers": [
{
"account_number_id": "acno_2N9g8VZKfCRXItzIV7bev39KlQ5",
"amount": 100,
"bank_account_id": "bacc_2N9g8VbA3n5NCh068GQwD5hrlS0",
"beneficiary_account_number": "403943517509507",
"beneficiary_counterparty_id": "cpty_2Jq2AyMFZhulLdrlBHcJw17SPGa",
"beneficiary_name": "Yellen Cocktails, LLC",
"currency_code": "USD",
"id": "wdrw_2N9lWiJF2bGit9RGxOuWpAfrnKP",
"imad": "20230317I1B7032R00000",
"is_incoming": true,
"message_identifier": "20230317I1B7032R00000",
"originator_account_number": "",
"originator_name": "",
"originator_to_beneficiary_information": null,
"received_at": "2023-03-17T19:06:52Z",
"receiver_di_name": "Yellen Cocktails, LLC",
"receiver_di_routing_number": "121145307",
"sender_di_name": "WELLS FARGO SF",
"sender_di_routing_number": "121000248",
"status": "received",
"supplementary_beneficiary_counterparty_id": "",
"wire_transfer_id": ""
}
],
"has_more": true
}
Create a wire drawdown request
POST
/transfers/wire/drawdown
Sends an outgoing wire drawdown to request funds from an external account.
body parameters
recipient_description
string
Required
A description sent to the external bank conveying information about the purpose of the drawdown (e.g. details of the payment, invoice numbers, identifiers). Must adhere to Fedwire character validation.
amount
int64
Required
Amount (in cents) to be requested.
e.g. $1.75 would be represented by 175
currency_code
string
Required
The three-letter currency code defined in ISO 4217. e.g. USD
beneficiary_account_number_id
string
Optional
ID of the account number that will receive funds if the drawdown is approved. If this is specified, beneficiary_bank_account_id
does not need to be included.
beneficiary_account_number_id
or beneficiary_bank_account_id
is required
beneficiary_bank_account_id
string
Optional
ID of the bank account that will receive funds if the drawdown is approved. If this is specified, beneficiary_account_number_id
does not need to be included. The default account number on bank_account_id
will be used.
beneficiary_account_number_id
or beneficiary_bank_account_id
is required
recipient_counterparty_id
string
Required
ID of the counterparty
the drawdown request will be sent to and funds requested from.
Note: A wire object must be attached to the counterparty
. If it is not, this request will fail.
Request
curl 'https://api.column.com/transfers/wire/drawdown' \
-X POST \
-u :<YOUR API KEY>
Response
{
"account_number_id": "acno_2VdcHCs6QSKE9MMQUlHUYEhmXD3",
"amount": 1200,
"bank_account_id": "bacc_2VdcHC0sougz5z7KKx1zxvBnEbd",
"beneficiary_account_number": "1234567890",
"beneficiary_counterparty_id": "cpty_2VddNPqm17UgAI0cq0dAJv7fQsd",
"beneficiary_name": "Vandelay Industries",
"beneficiary_reference": "M60WTZS6K32WAGWM",
"currency_code": "USD",
"description": "Invoice 21873 for import export services",
"id": "wdrw_2hWshSjdN9XYhpWiaSGEfOJ03FE",
"imad": "20240607MMQFMP2U000000",
"is_incoming": false,
"message_identifier": "20240607MMQFMP2U000000",
"originator_account_number": "987654321",
"originator_name": "HE Pennypacker",
"originator_to_beneficiary_information": [
"Invoice 21873 for import export",
"services",
"",
""
],
"receiver_di_name": "BANK OF MONEY",
"receiver_di_routing_number": "111111111",
"sender_di_name": "COLUMN NA",
"sender_di_routing_number": "121145307",
"sent_at": null,
"status": "initiated"
}
Foreign exchange rate sheet object
The foreign exchange rate sheet object includes FX rates for all foreign currencies that Column supports. This rate sheet is informational only and should be used to display FX rates to your customers. You can read about more about international wires and creating FX quotes here.
object parameters
data
array
List of FX rates for all supported currencies.
buy_currency_code
string
Buy currency. The three-letter currency code defined in ISO 4217. e.g. USD
rate
string
The FX rate used for currency exchange from sell_currency_code
to buy_currency_code
, including FX rate margin charged by your platform. Read more
rate_without_margin
string
The FX rate used for currency exchange from sell_currency_code
to buy_currency_code
, excluding FX rate margin charged by your platform. Read more
sell_currency_code
string
Sell currency. The three-letter currency code defined in ISO 4217. e.g. USD
updated_at
string
The timestamp at which the FX rate was last refreshed.
fx_rate_margin_bps
int
Foreign currency exchange margin charged by your platform to your customers in Basis Points (BPS). 1 bps
equals 0.01%
. Read more
supported_currencies
int
Number of supported currencies
Foreign Exchange Rate object
{
"data": [
{
"buy_currency_code": "CNY",
"rate": "7.181206726",
"rate_without_margin": "7.188316832",
"sell_currency_code": "USD",
"updated_at": "2023-08-30T17:20:17Z"
},
{
"buy_currency_code": "EUR",
"rate": "0.902563814",
"rate_without_margin": "0.903457442",
"sell_currency_code": "USD",
"updated_at": "2023-08-30T17:20:17Z"
},
{
"buy_currency_code": "JPY",
"rate": "144.045499505",
"rate_without_margin": "144.188118812",
"sell_currency_code": "USD",
"updated_at": "2023-08-30T17:20:17Z"
},
...
],
"fx_rate_margin_bps": 10,
"supported_currencies": 138
}
Get FX rate sheet
GET
/transfers/international-wire/fx-rate-sheet
Retrieve the FX rate sheet for all foreign currencies that Column supports.
Request
curl 'https://api.column.com/transfers/international-wire/fx-rate-sheet' \
-u :<YOUR API KEY>
Response
{
"data": [
{
"buy_currency_code": "CNY",
"rate": "7.181206726",
"rate_without_margin": "7.188316832",
"sell_currency_code": "USD",
"updated_at": "2023-08-30T17:20:17Z"
},
{
"buy_currency_code": "EUR",
"rate": "0.902563814",
"rate_without_margin": "0.903457442",
"sell_currency_code": "USD",
"updated_at": "2023-08-30T17:20:17Z"
},
{
"buy_currency_code": "JPY",
"rate": "144.045499505",
"rate_without_margin": "144.188118812",
"sell_currency_code": "USD",
"updated_at": "2023-08-30T17:20:17Z"
},
...
],
"fx_rate_margin_bps": 10,
"supported_currencies": 138
}
Foreign exchange quote object
The Foreign Exchange Quote object represents the rate quote for an international wire transfer. Read about more about international wire transfers here.
object parameters
buy_amount
int64
Buy amount (in the smallest unit of the currency) of the quote.
e.g., 1756
means 1.756 in KWD, 17.56 in USD, or 1756 in JPY.
buy_currency_code
string
Buy currency. The three-letter currency code defined in ISO 4217. e.g. USD
created_at
string
The timestamp when the FX quote was created.
expired_at
string
If this quote has not been booked yet, this is the deadline to book it. If this quote has already been booked, this is the deadline to use it to initiate an outgoing transfer. It is set as 16:30 ET on its rate date after it is booked. If this quote is not booked or used for an outgoing transfer after this deadline, it will be automatically canceled.
id
string
The ID of the FX quote.
rate
string
The foreign exchange rate used for currency exchange from sell_currency
to buy_currency
.
rate_date
string
The deadline to use this quote to initiate outgoing transfers. Format: YYYY-MM-DD
.
sell_amount
int64
Sell amount (in the smallest unit of the currency) of the quote.
e.g., 1756
means 1.756 in KWD, 17.56 in USD, or 1756 in JPY.
sell_currency_code
string
Sell currency. The three-letter currency code defined in ISO 4217. e.g. USD
status
string
The current status of the FX quote. Possible statuses are:
not_booked
: the FX quote has been requested but not yet booked. If you want to use it for an outgoing transfer, it must be booked beforeexpired_at
.booked
: the FX quote has been booked. It can be used for an outgoing transfer beforeexpired_at
.canceled
: the FX quote has been canceled, and can no longer be used for an outgoing transfer.used
: the FX quote has been used for an outgoing transfer.failed
: the FX quote is failed to be booked.
updated_at
string
The timestamp when the FX quote was updated.
Foreign Exchange Quote Object
{
"buy_amount": 100000,
"buy_currency_code": "CNY",
"created_at": "2022-09-29T19:16:58Z",
"expired_at": "2022-09-29T19:31:28Z",
"id": "fxqt_2FSINZ1O21ncdarR7GITr9kAgr6",
"rate": "6.8546",
"rate_date": "2022-09-29",
"sell_amount": 14589,
"sell_currency_code": "USD",
"status": "not_booked",
"updated_at": "2022-09-29T19:16:58.998Z"
}
Request a foreign exchange quote
POST
/transfers/international-wire/fx-rate
Request a foreign exchange quote to exchange USD
to other currencies for international wire transfers. Quotes are not booked until they are used in transfer requests.
body parameters
buy_amount
int64
Required
Buy amount (in the smallest unit of the currency) of the quote.
e.g., 1756
means 1.756 in KWD, 17.56 in USD, or 1756 in JPY.
buy_currency_code
string
Required
Buy currency. The three-letter currency code defined in ISO 4217. e.g. EUR
rate_date
string
Optional
Desired date for this FX quote. Format: YYYY-MM-DD
. If buy_currency_code='CAD'
, max rate dates are one business day after the current dates. For any other currencies, max rate dates are two business days after the current dates. After 5pm EST will be considered the following business day for booking rate date's in the future.
book_directly
bool
Optional
By default (i.e., book_directly=false
), we will query FX quotes only, and they are not booked until they are used to initiate outgoing transfers before they expire. However, if you need to initiate outgoing transfers after their expiration times (e.g., outgoing funds will not be available until next business day), you can book FX quotes directly by setting book_directly=true
. Booked FX quotes will be valid for a few days, depending on their correspondent banks.
A FX quote should be booked only with the intention of completing a transfer. If you do not intend to use a booked FX quote, it should be canceled as soon as possible. You may incur costs associated with canceling booked FX quotes given FX rate fluctuations.
Request
curl https://api.column.com/transfers/international-wire/fx-rate \
-XPOST \
-u :<YOUR API KEY> \
-d buy_amount=100000 \
-d buy_currency_code=CNY
Response
{
"buy_amount": 100000,
"buy_currency_code": "CNY",
"created_at": "2022-09-29T19:16:58Z",
"expired_at": "2022-09-29T19:31:28Z",
"id": "fxqt_2FSINZ1O21ncdarR7GITr9kAgr6",
"rate": "6.8546",
"rate_date": "2022-09-29",
"sell_amount": 14589,
"sell_currency_code": "USD",
"status": "not_booked",
"updated_at": "2022-09-29T19:16:58.998Z"
}
Get a foreign exchange quote
GET
/transfers/international-wire/fx-rate/<fx_quote_id>
Retrieve a single foreign exchange quote by its ID
path parameters
fx_quote_id
string
Required
ID of the foreign exchange quote you're looking up.
Request
curl 'https://api.column.com/transfers/international-wire/fx-rate/fxqt_2PIDTFK8uWYeTV1SD9ybNiWMx9e' \
-u :<YOUR API KEY>
Response
{
"id": "fxqt_2PIDTFK8uWYeTV1SD9ybNiWMx9e",
"created_at": "2023-05-03T17:41:48Z",
"updated_at": "2023-05-03T17:41:48Z",
"rate": "6.8546",
"rate_date": "2023-05-05",
"expired_at": "2023-05-03T17:56:18Z",
"sell_currency_code": "USD",
"sell_amount": 14589,
"buy_currency_code": "CNY",
"buy_amount": 100000,
"status": "used"
}
Book a foreign exchange quote
POST
/transfers/international-wire/fx-rate/<fx_quote_id>/book
Book a single foreign exchange quote by its ID. If the quote has already been booked before, it will be returned.
Warning
A FX quote should be booked only with the intention of completing a transfer. If you do not intend to use a booked FX quote, it should be canceled as soon as possible. You may incur costs associated with canceling booked FX quotes given FX rate fluctuations.
path parameters
fx_quote_id
string
Required
ID of the foreign exchange quote you're booking.
Request
curl 'https://api.column.com/transfers/international-wire/fx-rate/fxqt_2PIDTFK8uWYeTV1SD9ybNiWMx9e/book' \
-XPOST \
-u :<YOUR API KEY>
Response
{
"id": "fxqt_2PIDTFK8uWYeTV1SD9ybNiWMx9e",
"created_at": "2023-05-03T17:41:48Z",
"updated_at": "2023-05-03T17:41:48Z",
"rate": "6.8546",
"rate_date": "2023-05-05",
"expired_at": "2023-05-03T17:56:18Z",
"sell_currency_code": "USD",
"sell_amount": 14589,
"buy_currency_code": "CNY",
"buy_amount": 100000,
"status": "booked"
}
Cancel a foreign exchange quote
POST
/transfers/international-wire/fx-rate/<fx_quote_id>/cancel
Cancel a single foreign exchange quote by its ID. If the quote has already been used by an outgoing transfer, it cannot be canceled. If the quote has already been canceled before, it will be returned.
Warning
If you do not intend to use a booked FX quote, it should be canceled as soon as possible. You may incur costs associated with canceling booked FX quotes given FX rate fluctuations.
path parameters
fx_quote_id
string
Required
ID of the foreign exchange quote you're canceling.
Request
curl 'https://api.column.com/transfers/international-wire/fx-rate/fxqt_2PIDTFK8uWYeTV1SD9ybNiWMx9e/cancel' \
-XPOST \
-u :<YOUR API KEY>
Response
{
"id": "fxqt_2PIDTFK8uWYeTV1SD9ybNiWMx9e",
"created_at": "2023-05-03T17:41:48Z",
"updated_at": "2023-05-03T17:41:48Z",
"rate": "6.8546",
"rate_date": "2023-05-05",
"expired_at": "2023-05-03T17:56:18Z",
"sell_currency_code": "USD",
"sell_amount": 14589,
"buy_currency_code": "CNY",
"buy_amount": 100000,
"status": "canceled"
}
International wire transfer object
The international wire transfer object represents the current state of a single international wire transfer initiated by or received by Column. International wire transfers are used to send/receive money to/from outside of the United States via the Swift network. The international wire transfer object exposes all relevant information about the wire transfer to developers. Read about more about international wire transfers here.
object parameters
account_number_id
string
ID of the account number that is sending/receiving the transfer.
allow_overdraft
bool
Allows the account to go negative for an outgoing transfer. The bank account needs to haveis_overdraftable
enabled with an overdraft reserve account linked to it
amount
int64
Amount (in the smallest unit of the currency) of the funds that will be debited from the originator account for an outgoing transfer (including all fees), or credited to the beneficiary account for an incoming transfer (after deducting any fees).
e.g. $1.75 would be represented by 175
. Read more.
bank_account_id
string
ID of the bank account that is sending/receiving the transfer.
beneficiary_account_number
string
The account number of the beneficiary.
beneficiary_address
object
The address of the beneficiary.
line_1
string
Address line 1
line_2
string
Address line 2
city
string
City
state
string
State name. For US addresses, this field is mandatory and only postal abbreviations (e.g. AL, CA, DE, ...
) are allowed.
postal_code
string
Postal code
country_code
string
ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
).
beneficiary_fi
string
The Swift BIC code of the beneficiary's financial institution.
beneficiary_name
string
The name of the beneficiary.
cancellation_reason
string
The reason if the transfer is requested to be canceled (Read more).
cancellation_status
string
The status of cancellation request (Read more). Possible statuses are pending
, accepted
, and rejected
.
charge_bearer
string
The charge bearer code. Can be DEBT
, CRED
, or SHAR
. Read more.
charges
object
List of fees charged by financial institutions involved in this transfer. These charges are inclusive of both the wire the wire return if applicable. Charges are only listed here if the intermediary and beneficiary banks are part of the SWIFT GPI tracking system.
amount
int64
Charge amount (in the smallest unit of the currency).
e.g., 1756
means 1.756 in KWD, 17.56 in USD, or 1756 in JPY.
currency_code
string
Charge currency. The three-letter currency code defined in ISO 4217 (e.g. USD
)
agent
string
The Swift BIC code of the financial institution that applied the charge. It may be empty as some financial institutions do not provide it.
column_fixed_fee
int64
The amount (in the smallest unit of currency_code
) of fixed fee charged by Column for an outgoing transfer. This is not included in the charges
field.
e.g., 1756
means 1.756 in KWD, 17.56 in USD, or 1756 in JPY.
completed_at
string
The timestamp when the international wire was completed.
counterparty_id
string
ID of the counterparty
that is receiving/sending the transfer.
created_at
string
The timestamp when the international wire was created.
currency_code
string
Currency of amount
. The three-letter currency code defined in ISO 4217 (e.g. USD
). Read more.
description
string
The description of the transfer visible only in your platform.
end_to_end_id
string
Unique ID to unambiguously identify the transaction. This ID is passed on, unchanged, throughout the entire end-to-end chain, and can be used for reconciliation or to link tasks relating to the transaction. It can be included in several messages related to the transaction.
For example, an originator sent a transfer to pay an invoice. However, its amount is not enough to pay off the balance due to FX fluctuations, fees charged by intermediary banks. The originator may send another transfer with a different uetr
, but the same end_to_end_id
to link those two transfers.
Note: while uetr
is globally unique for each transfer, end_to_end_id
is unique only within originating banks (it may be only unique within certain time periods).
fx_quote_id
string
The ID of the foreign exchange quote.
fx_rate
string
The foreign exchange rate used for currency exchange of this transfer, including your platform FX rate margin markup. Read more
id
string
The ID of this international wire transfer.
idempotency_key
string
The idempotency key specified in the wire transfer.
initiated_at
string
The timestamp when the international wire was initiated.
instructed_amount
int64
Instructed amount (in the smallest unit of the currency) of the transfer. Read more.
e.g., 1756
means 1.756 in KWD, 17.56 in USD, or 1756 in JPY.
instructed_currency_code
string
Instructed currency. The three-letter currency code defined in ISO 4217 (e.g. USD
). Read more.
instruction_id
string
Unique ID assigned by the sender of this message.
instruction_to_beneficiary_fi
string
Further information for the beneficiary's financial institution.
intermediary_fis
array
The Swift BIC codes of intermediary financial institutions.
is_incoming
boolean
Indicates whether the wire transfer was incoming (true
or outgoing false
)
manual_review_at
string
The timestamp when the international wire went into the manual review state.
originator_account_number
string
The account number of the originator.
originator_address
object
The address of the originator.
line_1
string
Address line 1
line_2
string
Address line 2
city
string
City
state
string
State name. For US addresses, this field is mandatory and only postal abbreviations (e.g. AL, CA, DE, ...
) are allowed.
postal_code
string
Postal code
country_code
string
ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
).
originator_fi
string
The Swift BIC code of the originator's financial institution.
originator_name
string
The name of the originator.
pending_submission_at
string
The timestamp when the international wire was pending for submission.
platform_fixed_fee
int64
The amount (in the smallest unit of the currency_code
) of fixed fee charged by your platform for an outgoing transfer. This is not included in the charges
field.
e.g., 1756
means 1.756 in KWD, 17.56 in USD, or 1756 in JPY.
platform_fx_fee
int64
The amount (in the smallest unit of the currency_code
) of FX fee charged by your platform for an outgoing FX transfer. This is not included in the charges
field.
e.g., 1756
means 1.756 in KWD, 17.56 in USD, or 1756 in JPY.
raw_message
string
Raw initial transfer message in the Swift MT103 or ISO 20022/MX pacs.008
format. Only populated if it is queried with expand=raw_message
parameter.
remittance_info
object
Information supplied to enable the matching of an entry with the items that the transfer is intended to settle, such as commercial invoices in an account's receivable system. We will support more structured information soon (e.g., tax, invoicer, invoicee, etc.). They will be sent in F70
in MT103
messages, or RmtInf
in pacs.008.001.xx
messages. More details. Must adhere to International Wire character validation .
general_info
string
General information for the beneficiary in an unstructured form. Maximum length: 140
characters.
beneficiary_reference
string
Reference for the beneficiary (e.g., invoice number) to reconcile this transfer with their internal records. Maximum length: 30
characters.
return_reason
string
The reason if this transfer is returned.
returned_amount
int64
The amount (in the smallest unit of the currency) if this transfer is returned. Read more.
e.g., 1756
means 1.756 in KWD, 17.56 in USD, or 1756 in JPY.
returned_at
string
The timestamp when the international wire was returned.
returned_currency_code
string
The currency if this transfer is returned. The three-letter currency code defined in ISO 4217 (e.g. USD
). Read more.
settled_amount
int64
Settlement amount (in the smallest unit of the currency) of the transfer. Read more.
e.g., 1756
means 1.756 in KWD, 17.56 in USD, or 1756 in JPY.
settled_currency_code
string
Settlement currency. The three-letter currency code defined in ISO 4217 (e.g. USD
). Read more.
settlement_date
string
The date (in ET time zone) when funds are sent to the beneficiary bank for an outgoing transfer, or received from the originator bank for an incoming transfer. Format: YYYY-MM-DD
.
status
string
The current status of the international wire transfer. This internal status is different from the tracking status of tracking object (Read more). Possible statuses are initiated
, manual_review
,pending_submission
, submitted
, completed
,pending_return
and returned
.
submitted_at
string
The timestamp when the international wire was submitted to the Swift network.
uetr
string
Universally unique ID to provide an end-to-end reference for this transfer. Format: UUID v4.
ultimate_beneficiary_address
object
The address of the ultimate beneficiary to which this transfer is due.
line_1
string
Address line 1
line_2
string
Address line 2
city
string
City
state
string
State name. For US addresses, this field is mandatory and only postal abbreviations (e.g. AL, CA, DE, ...
) are allowed.
postal_code
string
Postal code
country_code
string
ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
).
ultimate_beneficiary_name
string
The name of the ultimate beneficiary to which this transfer is due.
ultimate_originator_address
object
The address of the ultimate party that owes an amount to the (ultimate) beneficiary.
line_1
string
Address line 1
line_2
string
Address line 2
city
string
City
state
string
State name. For US addresses, this field is mandatory and only postal abbreviations (e.g. AL, CA, DE, ...
) are allowed.
postal_code
string
Postal code
country_code
string
ISO 3166-1 Alpha-2 Country Code (e.g., US, FR, UK, DE, ...
).
ultimate_originator_name
string
The name of the ultimate party that owes an amount to the (ultimate) beneficiary.
updated_at
string
The timestamp when the international wire was updated.
International Wire Transfer Object
{
"account_number_id": "acno_2F37RhDUnWtB4GD9JXQEDYu7YAY",
"allow_overdraft": false,
"amount": "17965",
"bank_account_id": "bacc_2F37RbG3NZAr7Yn2d1i5hITz9O4",
"beneficiary_account_number": "1234567890",
"beneficiary_address": {
"city": "London",
"country_code": "GB",
"line_1": "123 Threadneedle Street",
"line_2": "",
"postal_code": "EC2R 8AH",
"state": "LND"
},
"beneficiary_fi": "BKENGB20",
"beneficiary_name": "Bob Trimble",
"charge_bearer": "SHAR",
"charges": [
{
"amount": "500",
"currency_code": "USD",
"agent": "CLNOUS66"
},
{
"amount": "500",
"currency_code": "CNY",
"agent": "CHASGBGLT"
}
],
"completed_at": null,
"counterparty_id": "cpty_2ESSJPnpof38GraQR5C6EnfFGKw",
"created_at": "2022-09-20T21:55:31Z",
"currency_code": "USD",
"description": "Swift transfer with CNY",
"end_to_end_id": "",
"fx_quote_id": "fxqt_2F3BY6XCpKQUy5cGCqPgLf3Kit7",
"fx_rate": "6.872100000",
"id": "swft_2F3BYA9aMdHag8iUtsDE8ji0KOK",
"idempotency_key": null,
"initiated_at": "2022-09-20T21:55:31Z",
"instructed_amount": "123456",
"instructed_currency_code": "CNY",
"instruction_id": "XF7MBKI09TUNZXIL",
"instruction_to_beneficiary_fi": "please contact with the beneficiary before releasing the funds",
"is_incoming": false,
"manual_review_at": null,
"originator_account_number": "366763686659680",
"originator_address": {
"city": "San Francisco",
"country_code": "US",
"line_1": "12345 Mission St.",
"line_2": "",
"postal_code": "94016",
"state": "CA"
},
"originator_fi": "CLNOUS66",
"originator_name": "Alice Biden",
"pending_submission_at": "2022-09-20T21:55:32Z",
"raw_message": null,
"remittance_info": {
"general_info": "downpayment for mortgage ID 123546"
},
"return_reason": null,
"returned_amount": null,
"returned_at": null,
"returned_currency_code": null,
"settled_amount": "123456",
"settled_currency_code": "CNY",
"settlement_date": "2022-09-20",
"status": "submitted",
"submitted_at": "2022-09-20T21:59:16Z",
"uetr": "d6e4313a-e186-4b21-83a5-43fa4cbaa38e",
"ultimate_beneficiary_address": null,
"ultimate_beneficiary_name": "",
"ultimate_originator_address": null,
"ultimate_originator_name": "",
"updated_at": "2022-09-20T22:09:18Z"
}
Create an international wire transfer
POST
/transfers/international-wire
Create an international wire transfer between a Column account and a counterparty. Transfer status can be tracked via the Tracking API.
body parameters
account_number_id
string
Optional
ID of the account number that is sending the transfer. If this is specified, the bank_account_id
does not need to be included.
account_number_id
or bank_account_id
is required
allow_overdraft
boolean
Optional
Allows the account to go negative for an outgoing transfer. The bank account needs to haveis_overdraftable
enabled with an overdraft reserve account linked to it
amount
int64
Required
Amount (in the smallest unit of the currency) of the funds that will be transferred between originator and counterparty accounts.
e.g., 1756
means 1.756 in KWD, 17.56 in USD, or 1756 in JPY.
bank_account_id
string
Optional
ID of the bank number that is sending the transfer. If no account_number_id
is specified, the default account number on bank_account_id
is used.
account_number_id
or bank_account_id
is required
charge_bearer
string
Optional
The charge bearer code. Can be SHAR
(default) DEBT
, or CRED
. Read more.
counterparty_id
string
Required
ID of the counterparty
that will receive the transfer
Note: A wire object must be attached to the counterparty
. If it is not, this request will fail.
currency_code
string
Required
The three-letter currency code defined in ISO 4217. e.g. EUR
. If USD
is specified as the currency_code
we will discard any provided fx_quote_id
and send the transfer in USD.
description
string
Optional
A description of the transfer visible only in your platform. Maximum length: 255
characters.
fx_quote_id
string
Optional
ID of the foreign exchange quote returned by FX Quote API. If it is not specified, we will automatically book a FX quote for this transfer if the currency is not USD
.
intermediary_bank
string
Optional
BIC of the intermediary bank. We will route the transfer request to the given intermediary bank. It will then forward the transfer request to the beneficiary bank.
Note: we use the routing table from Swift to decide the optimal routes to beneficiary banks if this parameter is not set. If you set an incorrect intermediary bank that has no routing information to the beneficiary bank, your transfer request will be returned. So please only set this parameter at your risk.
message_to_beneficiary_bank
string
Optional
Further information for the beneficiary's financial institution, which is sent in F72
in MT103
messages, or InstrForCdtrAgt
in pacs.008.001.xx
messages. Maximum length: 140
characters. Must adhere to International Wire character validation .
remittance_info
object
Optional
Information supplied to enable the matching of an entry with the items that the transfer is intended to settle, such as commercial invoices in an account's receivable system. We will support more structured information soon (e.g., tax, invoicer, invoicee, etc.). They will be sent in F70
in MT103
messages, or RmtInf
in pacs.008.001.xx
messages. More details. Must adhere to International Wire character validation .
general_info
string
Optional
General information for the beneficiary in an unstructured form. Maximum length: 140
characters.
beneficiary_reference
string
Optional
Reference for the beneficiary (e.g., invoice number) to reconcile this transfer with their internal records. Maximum length: 30
characters.
purpose_code
string
Optional
Purpose code of this transfer. Maximum length: 35
characters. More details.
Request
curl https://api.column.com/transfers/international-wire \
-XPOST \
-u :<YOUR API KEY> \
-d description="Swift transfer with CNY" \
-d message_to_beneficiary_bank="please contact with the beneficiary before releasing the funds" \
-d "remittance_info[general_info]"="downpayment for mortgage ID 123546" \
-d amount=123456 \
-d currency_code=CNY \
-d bank_account_id=bacc_2F37RbG3NZAr7Yn2d1i5hITz9O4 \
-d counterparty_id=cpty_2ESSJPnpof38GraQR5C6EnfFGKw
Response
{
"account_number_id": "acno_2F37RhDUnWtB4GD9JXQEDYu7YAY",
"allow_overdraft": false,
"amount": 17965,
"bank_account_id": "bacc_2F37RbG3NZAr7Yn2d1i5hITz9O4",
"beneficiary_account_number": "1234567890",
"beneficiary_address": {
"city": "London",
"country_code": "GB",
"line_1": "123 Threadneedle Street",
"line_2": "",
"postal_code": "EC2R 8AH",
"state": "LND"
},
"beneficiary_fi": "BKENGB20",
"beneficiary_name": "Bob Trimble",
"charge_bearer": "SHAR",
"charges": [
{
"amount": 500,
"currency_code": "USD",
"agent": "CLNOUS66"
},
{
"amount": 500,
"currency_code": "CNY",
"agent": "CHASGBGLT"
}
],
"completed_at": null,
"counterparty_id": "cpty_2ESSJPnpof38GraQR5C6EnfFGKw",
"created_at": "2022-09-20T21:55:31Z",
"currency_code": "USD",
"description": "Swift transfer with CNY",
"end_to_end_id": "",
"fx_quote_id": "fxqt_2F3BY6XCpKQUy5cGCqPgLf3Kit7",
"fx_rate": "6.872100000",
"id": "swft_2F3BYA9aMdHag8iUtsDE8ji0KOK",
"idempotency_key": null,
"initiated_at": "2022-09-20T21:55:31Z",
"instructed_amount": 123456,
"instructed_currency_code": "CNY",
"instruction_id": "XF7MBKI09TUNZXIL",
"instruction_to_beneficiary_fi": "please contact with the beneficiary before releasing the funds",
"is_incoming": false,
"manual_review_at": null,
"originator_account_number": "366763686659680",
"originator_address": {
"city": "San Francisco",
"country_code": "US",
"line_1": "12345 Mission St.",
"line_2": "",
"postal_code": "94016",
"state": "CA"
},
"originator_fi": "CLNOUS66",
"originator_name": "Alice Biden",
"pending_submission_at": "2022-09-20T21:55:32Z",
"raw_message": null,
"remittance_info": {
"general_info": "downpayment for mortgage ID 123546"
},
"return_reason": null,
"returned_amount": null,
"returned_at": null,
"returned_currency_code": null,
"settled_amount": 123456,
"settled_currency_code": "CNY",
"settlement_date": "2022-09-20",
"status": "submitted",
"submitted_at": "2022-09-20T21:59:16Z",
"uetr": "d6e4313a-e186-4b21-83a5-43fa4cbaa38e",
"ultimate_beneficiary_address": null,
"ultimate_beneficiary_name": "",
"ultimate_originator_address": null,
"ultimate_originator_name": "",
"updated_at": "2022-09-20T22:09:18Z"
}
Get international wire transfer
GET
/transfers/international-wire/<swift_transfer_id>
Retrieve a single international wire transfer by its ID
path parameters
swift_transfer_id
string
Required
ID of the Swift transfer you're looking up.
query parameters
expand
string
Optional
List of fields to be expanded (format: expand=field_1&expand=field_2&expand=field_3
).
raw_message
: raw initial transfer message in MT103 or ISO 20022/MXpacs.008
format
Request
curl 'https://api.column.com/transfers/international-wire/swft_2F3BYA9aMdHag8iUtsDE8ji0KOK?expand=raw_message' \
-u :<YOUR API KEY>
Response
{
"account_number_id": "acno_2F37RhDUnWtB4GD9JXQEDYu7YAY",
"allow_overdraft": false,
"amount": 17965,
"bank_account_id": "bacc_2F37RbG3NZAr7Yn2d1i5hITz9O4",
"beneficiary_account_number": "1234567890",
"beneficiary_address": {
"city": "London",
"country_code": "GB",
"line_1": "123 Threadneedle Street",
"line_2": "",
"postal_code": "EC2R 8AH",
"state": "LND"
},
"beneficiary_fi": "BKENGB20",
"beneficiary_name": "Bob Trimble",
"charge_bearer": "SHAR",
"charges": [
{
"amount": 500,
"currency_code": "USD",
"agent": "CLNOUS66"
},
{
"amount": 500,
"currency_code": "CNY",
"agent": "CHASGBGLT"
}
],
"completed_at": null,
"counterparty_id": "cpty_2ESSJPnpof38GraQR5C6EnfFGKw",
"created_at": "2022-09-20T21:55:31Z",
"currency_code": "USD",
"description": "Swift transfer with CNY",
"end_to_end_id": "",
"fx_quote_id": "fxqt_2F3BY6XCpKQUy5cGCqPgLf3Kit7",
"fx_rate": "6.872100000",
"id": "swft_2F3BYA9aMdHag8iUtsDE8ji0KOK",
"idempotency_key": null,
"initiated_at": "2022-09-20T21:55:31Z",
"instructed_amount": 123456,
"instructed_currency_code": "CNY",
"instruction_id": "XF7MBKI09TUNZXIL",
"instruction_to_beneficiary_fi": "please contact with the beneficiary before releasing the funds",
"is_incoming": false,
"manual_review_at": null,
"originator_account_number": "366763686659680",
"originator_address": {
"city": "San Francisco",
"country_code": "US",
"line_1": "12345 Mission St.",
"line_2": "",
"postal_code": "94016",
"state": "CA"
},
"originator_fi": "CLNOUS66",
"originator_name": "Alice Biden",
"pending_submission_at": "2022-09-20T21:55:32Z",
"raw_message": null,
"remittance_info": {
"general_info": "downpayment for mortgage ID 123546"
},
"return_reason": null,
"returned_amount": null,
"returned_at": null,
"returned_currency_code": null,
"settled_amount": 123456,
"settled_currency_code": "CNY",
"settlement_date": "2022-09-20",
"status": "submitted",
"submitted_at": "2022-09-20T21:59:16Z",
"uetr": "d6e4313a-e186-4b21-83a5-43fa4cbaa38e",
"ultimate_beneficiary_address": null,
"ultimate_beneficiary_name": "",
"ultimate_originator_address": null,
"ultimate_originator_name": "",
"updated_at": "2022-09-20T22:09:18Z"
}
List all international wire transfers
GET
/transfers/international-wire
Retrieve all international wire transfers under your platform
query parameters
bank_account_id
string
Optional
Return results associated with this bank account.
limit
int32
Optional
A limit of the number of objects to be returned, between 1
and 100
. The default is 10
.
starting_after
string
Optional
A cursor for use in pagination. starting_after
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with foo_ZXhhbXBsZQo
, your subsequent call can include starting_after=foo_ZXhhbXBsZQo
in order to fetch the next page of the list.
ending_before
string
Optional
A cursor for use in pagination. ending_before
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, starting with foo_ZXhhbXBsZQo=
, your subsequent call can include ending_before=foo_ZXhhbXBsZQo=
in order to fetch the previous page of the list.
created.gt
date-time
Optional
Return results where the specified time field is greater than this value.
created.gte
date-time
Optional
Return results where the specified time field is greater than or equal to this value.
created.lt
date-time
Optional
Return results where the specified time field is less than this value.
created.lte
date-time
Optional
Return results where the specified time field is less than or equal to this value.
Request
curl 'https://api.column.com/transfers/international-wire' \
-u :<YOUR API KEY>
Response
{
"transfers": [
{
"account_number_id": "acno_2F37RhDUnWtB4GD9JXQEDYu7YAY",
"allow_overdraft": false,
"amount": 17965,
"bank_account_id": "bacc_2F37RbG3NZAr7Yn2d1i5hITz9O4",
"beneficiary_account_number": "1234567890",
"beneficiary_address": {
"city": "London",
"country_code": "GB",
"line_1": "123 Threadneedle Street",
"line_2": "",
"postal_code": "EC2R 8AH",
"state": "LND"
},
"beneficiary_fi": "BKENGB20",
"beneficiary_name": "Bob Trimble",
"charge_bearer": "SHAR",
"charges": [
{
"amount": 500,
"currency_code": "USD",
"agent": "CLNOUS66"
},
{
"amount": 500,
"currency_code": "CNY",
"agent": "CHASGBGLT"
}
],
"completed_at": null,
"counterparty_id": "cpty_2ESSJPnpof38GraQR5C6EnfFGKw",
"created_at": "2022-09-20T21:55:31Z",
"currency_code": "USD",
"description": "Swift transfer with CNY",
"end_to_end_id": "",
"fx_quote_id": "fxqt_2F3BY6XCpKQUy5cGCqPgLf3Kit7",
"fx_rate": "6.872100000",
"id": "swft_2F3BYA9aMdHag8iUtsDE8ji0KOK",
"idempotency_key": null,
"initiated_at": "2022-09-20T21:55:31Z",
"instructed_amount": 123456,
"instructed_currency_code": "CNY",
"instruction_id": "XF7MBKI09TUNZXIL",
"instruction_to_beneficiary_fi": "please contact with the beneficiary before releasing the funds",
"is_incoming": false,
"manual_review_at": null,
"originator_account_number": "366763686659680",
"originator_address": {
"city": "San Francisco",
"country_code": "US",
"line_1": "12345 Mission St.",
"line_2": "",
"postal_code": "94016",
"state": "CA"
},
"originator_fi": "CLNOUS66",
"originator_name": "Alice Biden",
"pending_submission_at": "2022-09-20T21:55:32Z",
"raw_message": null,
"remittance_info": {
"general_info": "downpayment for mortgage ID 123546"
},
"return_reason": null,
"returned_amount": null,
"returned_at": null,
"returned_currency_code": null,
"settled_amount": 123456,
"settled_currency_code": "CNY",
"settlement_date": "2022-09-20",
"status": "submitted",
"submitted_at": "2022-09-20T21:59:16Z",
"uetr": "d6e4313a-e186-4b21-83a5-43fa4cbaa38e",
"ultimate_beneficiary_address": null,
"ultimate_beneficiary_name": "",
"ultimate_originator_address": null,
"ultimate_originator_name": "",
"updated_at": "2022-09-20T22:09:18Z"
}
],
"has_more": true
}
Return an incoming international wire
POST
/transfers/international-wire/<swift_transfer_id>/return
Return an incoming international wire transfer to the originator. Return status can be tracked via the Tracking API.
path parameters
swift_transfer_id
string
Required
body parameters
return_reason
string
Required
Reason for the return. Must be one of the following:
incorrect_beneficiary_account
: the beneficiary account number is incorrectbeneficiary_account_blocked
: the beneficiary account is blockedincorrect_amount
: transfer amount is not the same as expected by the beneficiarybeneficiary_mismatch
: beneficiary information in the wire does not match the corresponding information on the accountrefused_by_beneficiary
: the beneficiary refuses to accept this transfercancellation_requested
: the cancellation request from the originator is approvedfraud
: the transfer is a fraudcompliance_rejected
: the transfer did not pass compliance check
message_to_originator_bank
string
Optional
Additional information to the originator bank
Request
curl 'https://api.column.com/transfers/international-wire/<swift_transfer_id>/return' \
-XPOST \
-u :<YOUR API KEY> \
-d return_reason="incorrect_beneficiary_account" \
-d message_to_originator_bank="the beneficiary account number does not exist"
Response
{
"id": "swft_2IYWtUEUhEhSNXOEPfjzHAxaCzw",
"idempotency_key": null,
"bank_account_id": "bacc_2IYWtTssuLNF4DNUoEPUlXmv9iq",
"account_number_id": "acno_2IYWtWEgx9HtronSv2F5adAzKqS",
"counterparty_id": "cpty_2IYWtRzthJQiW8SyXcdGWPdqDAJ",
"status": "pending_return",
"is_incoming": true,
"allow_overdraft": false,
"description": null,
"fx_quote_id": "",
"return_reason": "incorrect_beneficiary_account",
"amount": 2918,
"currency_code": "USD",
"instructed_amount": 20000,
"instructed_currency_code": "CNY",
"settled_amount": 2918,
"settled_currency_code": "USD",
"settlement_date": "2022-12-06",
"returned_amount": 2918,
"returned_currency_code": "USD",
"created_at": "2022-12-06T20:40:12Z",
"updated_at": "2022-12-06T12:40:11.719-08:00",
"initiated_at": "2022-12-06T20:40:12Z",
"pending_submission_at": null,
"submitted_at": null,
"completed_at": "2022-12-06T20:40:12Z",
"returned_at": null,
"manual_review_at": null,
"end_to_end_id": null,
"uetr": "6a4796b7-a97e-43f6-afa1-d98b2ab90be3",
"fx_rate": "0.145887433",
"charge_bearer": "CRED",
"charges": [
{
"amount": 1000,
"currency_code": "USD",
"agent": ""
}
],
"originator_name": "John Britain",
"originator_address": {
"line_1": "96 Lairg Road",
"line_2": "",
"city": "New Winton",
"state": "",
"postal_code": "EH33 5ZN",
"country_code": "GB"
},
"originator_account_number": "GB29NWBK60161331926819",
"originator_fi": "BKENGB22",
"ultimate_originator_name": "",
"ultimate_originator_address": null,
"beneficiary_name": "Alice Milton",
"beneficiary_address": {
"line_1": "1 Mission St",
"line_2": "Apt 202",
"city": "San Francisco",
"state": "CA",
"postal_code": "94110",
"country_code": "US"
},
"beneficiary_account_number": "485989263105726",
"beneficiary_fi": "CLNOUS66",
"instruction_id": "XF7MBKI09TUNZXIL",
"instruction_to_beneficiary_fi": "POP/tax payment",
"ultimate_beneficiary_name": "",
"ultimate_beneficiary_address": null,
"remittance_info": { "general_info": "payment for invoice ABC-123" },
"raw_message": null
}
Cancel an outgoing international wire
POST
/transfers/international-wire/<swift_transfer_id>/cancel
Send a cancellation request to recall funds from the beneficiary for an outgoing international wire transfer. The beneficiary may approve or reject the cancellation request. Cancellation status can be tracked via the Tracking API.
path parameters
swift_transfer_id
string
Required
body parameters
cancellation_reason
string
Required
Reason for the cancellation. Must be one of the following:
incorrect_amount
: the transfer amount is incorrectincorrect_currency
: the transfer currency is incorrectduplicate
: the transfer was sent multiple times by mistakefraud
: the transfer is a fraudtech_failure
: the transfer was sent by mistake due to technical failurespayment_not_justified
: the transfer is missing some critical information required to process it successfullyrequested_by_originator
: any other reason requested by the originator
Request
curl 'https://api.column.com/transfers/international-wire/<swift_transfer_id>/cancel' \
-XPOST \
-u :<YOUR API KEY> \
-d cancellation_reason="duplicate"
Response
{
"account_number_id": "acno_2IYWtWEgx9HtronSv2F5adAzKqS",
"allow_overdraft": false,
"amount": 553,
"bank_account_id": "bacc_2IYWtTssuLNF4DNUoEPUlXmv9iq",
"beneficiary_account_number": "485989263105726",
"beneficiary_address": {
"city": "London",
"country_code": "GB",
"line_1": "123 Threadneedle Street",
"line_2": "",
"postal_code": "EC2R 8AH",
"state": "LND"
},
"beneficiary_fi": "BKENGB20",
"beneficiary_name": "Bob Trimble",
"cancellation_reason": "duplicate",
"cancellation_status": "pending",
"charge_bearer": "DEBT",
"charges": null,
"column_fixed_fee": 0,
"completed_at": "2023-08-22T06:52:40Z",
"counterparty_id": "cpty_2ESSJPnpof38GraQR5C6EnfFGKw",
"created_at": "2023-08-21T21:45:48Z",
"currency_code": "USD",
"description": "test cancellation of outgoing transfer",
"end_to_end_id": null,
"fx_quote_id": "fxqt_2F3BY6XCpKQUy5cGCqPgLf3Kit7",
"fx_rate": "0.904159132",
"id": "swft_2F3BYA9aMdHag8iUtsDE8ji0KOK",
"idempotency_key": null,
"initiated_at": "2023-08-21T21:45:48Z",
"instructed_amount": 500,
"instructed_currency_code": "EUR",
"instruction_id": "TQT1n61SqYWCjhTL",
"instruction_to_beneficiary_fi": "",
"intermediary_fis": ["CHASUS33FXS", "CHASDEFX", "BREXPLPW"],
"is_incoming": false,
"manual_review_at": null,
"originator_account_number": "366763686659680",
"originator_address": {
"city": "San Francisco",
"country_code": "US",
"line_1": "12345 Mission St.",
"line_2": "",
"postal_code": "94016",
"state": "CA"
},
"originator_fi": "CLNOUS66",
"originator_name": "Column NA",
"pending_submission_at": "2023-08-22T04:00:39Z",
"platform_fixed_fee": 0,
"platform_fx_fee": 0,
"raw_message": null,
"remittance_info": {
"beneficiary_reference": "",
"general_info": "invoice NO. 123456"
},
"return_reason": null,
"returned_amount": null,
"returned_at": null,
"returned_currency_code": null,
"settled_amount": 500,
"settled_currency_code": "EUR",
"settlement_date": "2023-08-22",
"status": "completed",
"submitted_at": "2023-08-22T04:00:40Z",
"uetr": "dbfefd8f-0156-4c47-830c-71d4eb1d4226",
"ultimate_beneficiary_address": null,
"ultimate_beneficiary_name": "",
"ultimate_originator_address": null,
"ultimate_originator_name": "",
"updated_at": "2023-08-22T17:07:08.383Z"
}
International wire tracking object
Read more.object parameters
cancellation_reason
string
The reason if the transfer is requested to be canceled. Read more.
cancellation_status
string
The latest status of cancellation request (Read more). Can be one of the following:
pending
: the beneficiary bank is still processing the cancellation request.accepted
: the beneficiary bank has accepted the cancellation request. Funds have been returned, or will be returned shortly.rejected
: the beneficiary bank has rejected the cancellation request. Funds won't be returned.
completed_at
string
The timestamp when the international wire was completed by the beneficiary bank.
completed_amount
int64
The amount (in the smallest unit of the currency) credited to the beneficiary account by the beneficiary bank.
e.g., 1756
means 1.756 in KWD, 17.56 in USD, or 1756 in JPY.
completed_currency_code
string
Currency code of the completed amount. The three-letter currency code defined in ISO 4217 (e.g. USD
). Read more.
events
object
List of tracking updates of the transfer in ascending order of event timestamp.
cancellation_reason
string
The reason if the transfer is requested to be canceled. Read more.
cancellation_status
string
The current status of cancellation request by this event (Read more). Can be one of the following:
pending
: the beneficiary bank is still processing the cancellation request.accepted
: the beneficiary bank has accepted the cancellation request. Funds have been returned, or will be returned shortly.rejected
: the beneficiary bank has rejected the cancellation request. Funds won't be returned.
cancellation_status_reason
string
The reason if the cancellation request is still pending
or rejected
.
charge_bearer
string
The charge bearer code. Can be DEBT
, CRED
, or SHAR
. Read more.
charges
object
List of fees charged by financial institutions involved in this transfer. These charges are inclusive of both the wire the wire return if applicable. Charges are only listed here if the intermediary and beneficiary banks are part of the SWIFT GPI tracking system.
amount
int64
Charge amount (in the smallest unit of the currency).
e.g., 1756
means 1.756 in KWD, 17.56 in USD, or 1756 in JPY.
currency_code
string
Charge currency. The three-letter currency code defined in ISO 4217 (e.g. USD
)
agent
string
The Swift BIC code of the financial institution that applied the charge. It may be empty as some financial institutions do not provide it.
fx_rate
string
The foreign exchange rate used for currency exchange by this financial institution.
instructed_amount
int64
Instructed amount (in the smallest unit of the currency) of the transfer. Read more.
e.g., 1756
means 1.756 in KWD, 17.56 in USD, or 1756 in JPY.
instructed_currency_code
string
Instructed currency. The three-letter currency code defined in ISO 4217 (e.g. USD
). Read more.
instructed_fi
string
The Swift BIC code of the instructed financial institution (i.e., the next FI in the routing).
is_cover_transfer_event
bool
Indicate if this event is for the cover transfer that settles funds. Cover transfer events will not impact the corresponding customer transfer status. Read more
network_reference
string
The event ID in the Swift tracking system. Unique per transfer.
settled_amount
int64
Settlement amount (in the smallest unit of the currency) of the transfer.
e.g., 1756
means 1.756 in KWD, 17.56 in USD, or 1756 in JPY.
settled_currency_code
string
Settlement currency. The three-letter currency code defined in ISO 4217 (e.g. USD
). Read more.
transfer_status
string
The current transfer status in the Swift tracking system by this event. This tracking status is different from the internal status of international wire object (Read more). Can be one of the following:
pending
: the transfer is still being processed by an intermediary bank or the beneficiary bank.rejected
: the transfer has been rejected by an intermediary bank or the beneficiary bank.completed
: the transfer has been processed successfully by the beneficiary bank, and funds have been credited to the beneficiary account.
transfer_status_reason
string
The reason if the transfer is still pending
or rejected
.
type
string
The tracking event type. Can be one of the following:
transfer_initiated
: the transfer is initiatedtransfer_updated
: the transfer status is updatedtransfer_cancellation_requested
: the originator has requested to cancel the transfertransfer_cancellation_responded
: the cancellation status is updatedtransfer_cancellation_tracking_updated
: the tracking status of cancellation request is updatedtransfer_return_initiated
: the transfer is returnedtransfer_return_updated
: the transfer return status is updatedtransfer_cover_initiated
: the cover transfer is initiatedtransfer_cover_updated
: the cover transfer status is updatedtransfer_cover_return_initiated
: the cover transfer is returnedtransfer_cover_return_updated
: the cover transfer return status is updated
updated_at
string
The timestamp when the event was lastly updated by the Swift Tracking system.
updated_by
string
The Swift BIC code of the financial institution posting this status update, or the Swift Tracking system (TRCKCHZZXXX
).
id
string
The ID of this international wire transfer.
transfer_status
string
The latest transfer status in the Swift tracking system. This tracking status is different from the internal status of international wire object (Read more). Can be one of the following:
pending
: the transfer is still being processed by an intermediary bank or the beneficiary bank.rejected
: the transfer has been rejected by an intermediary bank or the beneficiary bank.completed
: the transfer has been processed successfully by the beneficiary bank, and funds have been credited to the beneficiary account.
transfer_status_reason
string
The reason if the transfer is still pending
or rejected
.
uetr
string
Universally unique ID to provide an end-to-end reference for this transfer. Format: UUID v4.
updated_at
string
The timestamp when the transfer was lastly updated by the Swift tracking system.
International Wire Tracking Object
{
"cancellation_reason": null,
"cancellation_status": null,
"completed_amount": null,
"completed_at": null,
"completed_currency_code": null,
"events": [
{
"cancellation_reason": null,
"cancellation_status": null,
"cancellation_status_reason": null,
"charge_bearer": "DEBT",
"charges": null,
"fx_rate": null,
"instructed_amount": 500,
"instructed_currency_code": "EUR",
"instructed_fi": null,
"network_reference": "20230821CLNOUS66AXXX0161234567",
"settled_amount": 500,
"settled_currency_code": "EUR",
"transfer_status": "pending",
"transfer_status_reason": "Credit transfer has been forwarded to the next bank that does not provide tracking service",
"type": "transfer_initiated",
"updated_at": "2023-08-22T04:01:02Z",
"updated_by": "CLNOUS66XXX"
},
{
"cancellation_reason": null,
"cancellation_status": null,
"cancellation_status_reason": null,
"charge_bearer": "DEBT",
"charges": null,
"fx_rate": null,
"instructed_amount": 500,
"instructed_currency_code": "EUR",
"instructed_fi": null,
"network_reference": "swi00004-2023-08-22T04:03:08.44682.781207Z",
"settled_amount": 500,
"settled_currency_code": "EUR",
"transfer_status": "pending",
"transfer_status_reason": "Credit transfer has been forwarded to the next bank that does not provide tracking service",
"type": "transfer_initiated",
"updated_at": "2023-08-22T04:03:33Z",
"updated_by": "CHASUS33XXX"
}
],
"id": "swft_2F3BYA9aMdHag8iUtsDE8ji0KOK",
"transfer_status": "pending",
"transfer_status_reason": "Credit transfer has been forwarded to the next bank that does not provide tracking service",
"uetr": "d6e4313a-e186-4b21-83a5-43fa4cbaa38e",
"updated_at": "2023-08-22T04:03:33Z"
}
Get international wire tracking
GET
/transfers/international-wire/<swift_transfer_id_or_uetr>/tracking
Retrieve the tracking details of an international wire transfer by its ID or UETR. Read more.
path parameters
swift_transfer_id_or_uetr
string
Required
ID or UETR of the Swift transfer you're looking up.
Request
curl 'https://api.column.com/transfers/international-wire/swft_2F3BYA9aMdHag8iUtsDE8ji0KOK/tracking' \
-u :<YOUR API KEY>
curl 'https://api.column.com/transfers/international-wire/d6e4313a-e186-4b21-83a5-43fa4cbaa38e/tracking' \
-u :<YOUR API KEY>
Response
{
"cancellation_reason": null,
"cancellation_status": null,
"completed_amount": 500,
"completed_at": "2023-08-22T06:09:00Z",
"completed_currency_code": "EUR",
"events": [
{
"cancellation_reason": null,
"cancellation_status": null,
"cancellation_status_reason": null,
"charge_bearer": "DEBT",
"charges": null,
"fx_rate": null,
"instructed_amount": 500,
"instructed_currency_code": "EUR",
"instructed_fi": null,
"network_reference": "20230821CLNOUS66AXXX0161234567",
"settled_amount": 500,
"settled_currency_code": "EUR",
"transfer_status": "pending",
"transfer_status_reason": "Credit transfer has been forwarded to the next bank that does not provide tracking service",
"type": "transfer_initiated",
"updated_at": "2023-08-22T04:01:02Z",
"updated_by": "CLNOUS66XXX"
},
{
"cancellation_reason": null,
"cancellation_status": null,
"cancellation_status_reason": null,
"charge_bearer": "DEBT",
"charges": null,
"fx_rate": null,
"instructed_amount": 500,
"instructed_currency_code": "EUR",
"instructed_fi": null,
"network_reference": "swi00004-2023-08-22T04:03:08.44682.781207Z",
"settled_amount": 500,
"settled_currency_code": "EUR",
"transfer_status": "pending",
"transfer_status_reason": "Credit transfer has been forwarded to the next bank that does not provide tracking service",
"type": "transfer_initiated",
"updated_at": "2023-08-22T04:03:33Z",
"updated_by": "CHASUS33XXX"
},
{
"cancellation_reason": null,
"cancellation_status": null,
"cancellation_status_reason": null,
"charge_bearer": "DEBT",
"charges": null,
"fx_rate": null,
"instructed_amount": null,
"instructed_currency_code": null,
"instructed_fi": null,
"network_reference": "20230822CHASDEFXEXXX1681234567",
"settled_amount": 500,
"settled_currency_code": "EUR",
"transfer_status": "pending",
"transfer_status_reason": "Credit transfer has been forwarded to the next bank that does not provide tracking service",
"type": "transfer_updated",
"updated_at": "2023-08-22T06:08:00Z",
"updated_by": "CHASDEFXXXX"
},
{
"cancellation_reason": null,
"cancellation_status": null,
"cancellation_status_reason": null,
"charge_bearer": null,
"charges": null,
"fx_rate": null,
"instructed_amount": null,
"instructed_currency_code": null,
"instructed_fi": null,
"network_reference": "20230822BKENGB20AXXX6667680136",
"settled_amount": 500,
"settled_currency_code": "EUR",
"transfer_status": "completed",
"transfer_status_reason": null,
"type": "transfer_updated",
"updated_at": "2023-08-22T06:10:02Z",
"updated_by": "BKENGB20XXX"
}
],
"id": "swft_2F3BYA9aMdHag8iUtsDE8ji0KOK",
"transfer_status": "completed",
"transfer_status_reason": null,
"uetr": "d6e4313a-e186-4b21-83a5-43fa4cbaa38e",
"updated_at": "2023-08-22T17:22:18Z"
}
Realtime transfer object
The realtime transfer object represents the current state of a single realtime transfer initiated by or received by Column. Realtime transfers are used to send and receive money over FedNow or RTP. The realtime transfer object exposes all relevant information about the realtime transfer to developers. Read about more about realtime transfers here.
object parameters
accepted_at
string
The timestamp when the realtime was accepted without posting.
account_number_id
string
ID of the account number that is sending/receiving the transfer.
allow_overdraft
bool
Allows the account to go negative for an outgoing transfer. The bank account needs to haveis_overdraftable
enabled with an overdraft reserve account linked to it
amount
integer
Amount (in cents) of the funds that will be transferred between originator and counterparty accounts.
e.g. $1.75 would be represented by 175
bank_account_id
string
ID of the bank number that is sending/receiving the transfer.
blocked_at
string
The timestamp when the realtime was blocked after accepting without posting.
completed_at
string
The timestamp when the realtime was completed.
counterparty_id
string
ID of the counterparty
that is receiving/sending the transfer
currency_code
string
The three-letter currency code defined in ISO 4217. e.g. USD
description
string
A description of the transfer visible in people's accounts.
id
string
The unique id of the object.
idempotency_key
string
The idempotency key specified in the realtime transfer.
initiated_at
string
The timestamp when the realtime was initiated.
is_incoming
boolean
Indicates whether the realtime transfer was incoming (true
or outgoing false
)
is_on_us
boolean
Indicates whether the realtime transfer was between two bank accounts held at Column.
manual_review_approved_at
string
The timestamp when the realtime was approved after manual review.
manual_review_at
string
The timestamp when the realtime went into the manual review state.
manual_review_rejected_at
string
The timestamp when the realtime was rejected after manual review.
rejected_at
string
The timestamp when the realtime was rejected after accept without posting
status
string
The current status of the realtime transfer. Possible statuses are initiated
, pending
, accepted
, completed
, blocked
, rejected
, manual_review
, manual_review_approved
, manual_review_rejected
.
Realtime Transfer Object
{
"accepted_at": "2023-12-29T19:45:11Z",
"account_number_id": "acno_2XrFelm5efqwGkPsu3B1DtSEDDg",
"allow_overdraft": false,
"amount": 10000,
"bank_account_id": "bacc_2XrFelZxSUOXXTswfr0h9KByzNp",
"blocked_at": null,
"completed_at": "2023-12-29T19:45:13Z",
"counterparty_id": "cpty_2aELmewqaBj5Bp6oraJ7Pl6LH1p",
"currency_code": "USD",
"description": "Example realtime transfer",
"id": "rttr_2aEM6RbzozxcvVY11ArHJw1Ka4E",
"idempotency_key": null,
"initiated_at": "2023-12-29T19:45:10Z",
"is_incoming": false,
"is_on_us": false,
"manual_review_approved_at": null,
"manual_review_at": null,
"manual_review_rejected_at": null,
"pending_at": null,
"rejected_at": null,
"status": "completed"
}
Create a realtime transfer
POST
/transfers/realtime
Create a realtime transfer between a Column account and a counterparty.
body parameters
description
string
Optional
A description of the transfer visible in people's accounts.
amount
int64
Required
Amount (in cents) of the funds that will be transferred between originator and counterparty accounts.
e.g. $1.75 would be represented by 175
currency_code
string
Required
The three-letter currency code defined in ISO 4217. e.g. USD
account_number_id
string
Optional
ID of the account number that is sending the transfer. If this is specified, the bank_account_id
does not need to be included.
account_number_id
or bank_account_id
is required
bank_account_id
string
Optional
ID of the bank number that is sending the transfer. If no account_number_id
is specified, the default account number on bank_account_id
is used.
account_number_id
or bank_account_id
is required
counterparty_id
string
Required
ID of the counterparty
that will receive the transfer
allow_overdraft
boolean
Optional
Allows the account to go negative for an outgoing transfer. The bank account needs to haveis_overdraftable
enabled with an overdraft reserve account linked to it
Request
curl 'https://api.column.com/transfers/realtime' \
-XPOST \
-u :<YOUR API KEY> \
-d description="Example realtime transfer" \
-d amount=10000 \
-d currency_code="USD" \
-d bank_account_id="<bank_account_id>" \
-d counterparty_id="<counterparty_id>"
Response
{
"accepted_at": "2023-12-29T19:45:11Z",
"account_number_id": "acno_2XrFelm5efqwGkPsu3B1DtSEDDg",
"allow_overdraft": false,
"amount": 10000,
"bank_account_id": "bacc_2XrFelZxSUOXXTswfr0h9KByzNp",
"blocked_at": null,
"completed_at": "2023-12-29T19:45:13Z",
"counterparty_id": "cpty_2aELmewqaBj5Bp6oraJ7Pl6LH1p",
"currency_code": "USD",
"description": "Example realtime transfer",
"id": "rttr_2aEM6RbzozxcvVY11ArHJw1Ka4E",
"idempotency_key": null,
"initiated_at": "2023-12-29T19:45:10Z",
"is_incoming": false,
"is_on_us": false,
"manual_review_approved_at": null,
"manual_review_at": null,
"manual_review_rejected_at": null,
"pending_at": null,
"rejected_at": null,
"status": "completed",
"type": "fednow",
"uetr": "52330fe7-a9d0-404b-9848-6c925857c3b6"
}
List all realtime transfers
GET
/transfers/realtime
Retrieve all realtime transfers under your platform
query parameters
limit
int32
Optional
A limit of the number of objects to be returned, between 1
and 100
. The default is 10
.
starting_after
string
Optional
A cursor for use in pagination. starting_after
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with foo_ZXhhbXBsZQo
, your subsequent call can include starting_after=foo_ZXhhbXBsZQo
in order to fetch the next page of the list.
ending_before
string
Optional
A cursor for use in pagination. ending_before
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, starting with foo_ZXhhbXBsZQo=
, your subsequent call can include ending_before=foo_ZXhhbXBsZQo=
in order to fetch the previous page of the list.
Request
curl 'https://api.column.com/transfers/realtime' \
-u :<YOUR API KEY>
Response
{
"transfers": [
{
"accepted_at": "2023-12-29T19:45:11Z",
"account_number_id": "acno_2XrFelm5efqwGkPsu3B1DtSEDDg",
"allow_overdraft": false,
"amount": 10000,
"bank_account_id": "bacc_2XrFelZxSUOXXTswfr0h9KByzNp",
"blocked_at": null,
"completed_at": "2023-12-29T19:45:13Z",
"counterparty_id": "cpty_2aELmewqaBj5Bp6oraJ7Pl6LH1p",
"currency_code": "USD",
"description": "Example realtime transfer",
"id": "rttr_2aEM6RbzozxcvVY11ArHJw1Ka4E",
"idempotency_key": null,
"initiated_at": "2023-12-29T19:45:10Z",
"is_incoming": false,
"is_on_us": false,
"manual_review_approved_at": null,
"manual_review_at": null,
"manual_review_rejected_at": null,
"pending_at": null,
"rejected_at": null,
"status": "completed",
"type": "fednow",
"uetr": "52330fe7-a9d0-404b-9848-6c925857c3b6"
}
],
"has_more": true
}
Check transfer object
The check transfer object represents the current state of a single check transfer initiated by or received by Column. Check transfers are used to send and receive money over Check 21-Enabled services. The check transfer object exposes all relevant information about the check transfer to developers. Read about more about check transfers here.
object parameters
account_number_id
string
ID of the account number that is sending the transfer.
allow_overdraft
boolean
Allow the account to go negative for the transfer. The bank account needs to have is_overdraftable
enabled with an overdraft reserve account linked to it.
back_image
base 64 encoded image
Base 64 encoded TIFF image of the back of the deposited check image. This field is not populated in the check transfer object until after the check is deposited.
bank_account_id
string
ID of the bank number that is sending the transfer.
check_number
string
Sequence number of the check.
created_at
string
Date (format: YYYY-MM-DD
) on which the check was created.
currency_code
string
The three-letter currency code defined in ISO 4217. e.g. USD
deposited_amount
int64
Amount (in cents) of the funds that is deposited.
e.g. $1.75 would be represented by 175
deposited_at
string
Date (format: YYYY-MM-DD
) on which the check is deposited (applies only to check deposited at Column).
external_routing_number
string
For issued check, this is the routing number of bank of first deposit
description
string
A description of the transfer visible in people's accounts.
first_return_at
string
Date (format: YYYY-MM-DD
) on which the check is returned for the first time.
front_image
base 64 encoded image
Base 64 encoded TIFF image of the front of the deposited check image. This field is not populated in the check transfer object until after the check is deposited.
id
string
The unique id of the object.
idempotency_key
string
The idempotency key specified in the wire transfer.
micr_line
object
The MICR line is the sequence of numbers and characters at the bottom of a check.
amount_field
string
Amount of the issued check.
auxiliary_on_us
string
Auxiliary on us. This field is provided by the issuing bank and most commonly used for a check number. In many cases, auxiliary_on_us will be the string before a routing number in the MICR line.
external_processing_code
string
External processing code.
payor_bank_routing_number
string
Payor bank routing number.
on_us
string
On us. This field is provided by the issuing bank and most commonly contains both check number and account number. In many cases, on-us will be the string after a routing number in the MICR line.
payee_name
string
The name of the person who is receiving the check.
extracted_payee_name
string
The payee name extracted from the ICL file supplied by the bank of first deposit (for Column issued checks only). This can be compared to the payee name on the issued check to detect fraudulently altered checks. Not guaranteed to be accurate.
pending_deposit_at
string
Date (format: YYYY-MM-DD
) on which the check was pending deposit.
pending_first_return_at
string
Date (format: YYYY-MM-DD
) on which the check was pending first return.
pending_user_initiated_return_at
string
Date (format: YYYY-MM-DD
) on which the user initiates the return.
positive_pay_amount
int64
Amount (in cents) of the issued check that will be used in positive pay validation if account number is provided.
e.g. $1.75 would be represented by 175
.
reclear_at
string
Date (format: YYYY-MM-DD
) on which the check was recleared.
second_return_at
string
Date (format: YYYY-MM-DD
) on which the check was returned for the second time.
settled_at
string
Date (format: YYYY-MM-DD
) on which the check was settled.
status
string
The current status of the check transfer. Possible statuses are initiated
, issued
,manual_review
, rejected
, pending_deposit
, pending_stop
,deposited
, stopped
, pending_first_return
, pending_second_return
,first_return
, pending_reclear
, recleared
, second_return
, settled
,returned
, pending_user_initiated_return
, user_initiated_return_submitted
,user_initiated_returned
, and pending_user_initiated_return_dishonored
.
pending_stop_at
string
Date (format: YYYY-MM-DD
) on which the check was stopped.
stopped_at
string
Date (format: YYYY-MM-DD
) on which funds locked for a check in a pending_stop
state are made available.
type
string
Check transfer type. For checks deposited at Column, this is credit
. For checks issued by Column and deposited at another FI, this is debit
. Learn more here.
updated_at
string
The timestamp at which the Check transfer was lastly updated.
user_initiated_return_submitted_at
string
Date (format: YYYY-MM-DD
) on which the user initiated return is submitted to the Fed.
user_initiated_returned_at
string
Date (format: YYYY-MM-DD
) on which the user initiated return is completed.
user_initiated_return_dishonored_at
string
Date (format: YYYY-MM-DD
) on which the user initiated return is dishonored.
delivered_by_column
boolean
For issued check, whether this check is also mailed by Column.
message
string
Message to the payee. Only available for checks delivered by Column.
memo
string
Memo on the check. Only available for checks delivered by Column.
payee_address
object
The receiving address of the check. Only available for checks delivered by Column.
line_1
string
Address line 1
line_2
string
Address line 2
city
string
City
state
string
State name. For US addresses, only postal abbreviations (e.g. AL, CA, DE, ...
) are allowed.
postal_code
string
Postal code
country_code
string
Only US
is allowed for now.
delivery_status
string
The current delivery status of the check delivered by Column. Possible statuses are created
,mailed
, in_transit
, in_local_area
,processed_for_delivery
, delivered
, failed
, rerouted
, and returned_to_sender
.
is_preview_pdf_available
boolean
For check delivered by Column, whether the preview PDF is ready to be downloaded.
Check Transfer Object
{
"account_number_id": "acno_25nacNsLD8qLI1Vc6x67sxFU27c",
"back_image":"<base 64 encoded string>"
"bank_account_id": "bacc_25nVQr05nZybpyEzw8j0wV6VRUh",
"check_number": "1",
"created_at": "2022-03-02T00:05:54Z",
"currency_code": "USD",
"delivered_by_column": false,
"delivery_status": null,
"deposited_amount": "100000",
"deposited_amount": int64,
"deposited_at": null,
"description": "incoming check transfer",
"external_routing_number":"<BOFD routing number>",
"extracted_payee_name":"Alex Gold",
"first_return_at": null,
"front_image":"<base 64 encoded string>"
"id": "chkt_25o3LGGbxLjpabTm6zHquAM1ti2",
"idempotency_key": "",
"is_preview_pdf_available":false,
"issued_at": "2023-03-02T00:05:54Z",
"manual_review_at": null,
"memo": null,
"message": null,
"micr_line": {
"amount_field": "100000",
"auxiliary_on_us": "1001",
"external_processing_code": "",
"payor_bank_routing_number": "322271627",
"on_us": "12345678910"
},
"payee_address": null,
"payee_name": "Olive Column",
"pending_deposit_at": "2022-03-02T00:05:54Z",
"pending_first_return_at": null,
"pending_stop_at": null,
"pending_user_initiated_return_at": null,
"positive_pay_amount": int64,
"reclear_at": null,
"rejected_at": null,
"second_return_at": null,
"settled_at": "2022-03-02T00:05:54Z",
"status": "settled",
"stopped_at": null,
"type": "debit",
"updated_at": "2022-03-02T00:05:54Z",
"user_initiated_returned_at": null
}
Issue a check
POST
/transfers/checks/issue
Issue a check to a specific payee for a given amount.
If mail_check_request
is included, the check will be delivered by Column too.
body parameters
bank_account_id
string
Required
ID of the bank account from which the check will be issued.
account_number_id
or bank_account_id
is required.
account_number_id
string
Optional
Account number from which the check will be issued. If no account_number_id
is specified, the default account number on bank_account_id is used.
account_number_id
or bank_account_id
is required.
description
string
Optional
Description of the issued check visible only in your platform. Maximum length: 255
characters.
positive_pay_amount
int64
Required
Amount (in cents) of the issued check that will be used in positive pay validation if account number is provided.
e.g. $1.75 would be represented by 175
.
currency_code
string
Required
The three-letter currency code defined in ISO 4217. e.g. USD
payee_name
string
Required
Name of the payee or recipient of the issued check.
allow_overdraft
boolean
Optional
Allow the account to go negative for the transfer. The bank account needs to have is_overdraftable
enabled with an overdraft reserve account linked to it.
mail_check_request
object
Optional
Optional field to have Column to mail the check for you.
message
string
Required
Message to the payee. Maximum length: 400
characters.
memo
string
Optional
Memo on the check. Maximum length: 40
characters.
attachment_document_id
string
Optional
Optional - Document ID of a check_attachment
document. If provided, the document will be printed and included in the envelope. See Check Issuing, Printing and Mailing and Upload a document for more information.
payee_address
object
Required
The receiving address of the check.
line_1
string
Required
Address line 1
line_2
string
Optional
Address line 2
city
string
Required
City
state
string
Required
State name. For US addresses, only postal abbreviations (e.g. AL, CA, DE, ...
) are allowed.
postal_code
string
Required
Postal code
country_code
string
Required
Only US
is allowed for now.
payor_name
string
Required
Payor name to be printed on the check. Maximum length: 40
characters.
courtesy_of
string
Optional
"Courtesy of" line printed after payor name on the check. Maximum length: 40
characters.
payor_address
object
Required
The payor address to be printed on the check.
line_1
string
Required
Address line 1
line_2
string
Optional
Address line 2
city
string
Required
City
state
string
Required
State name. For US addresses, only postal abbreviations (e.g. AL, CA, DE, ...
) are allowed.
postal_code
string
Required
Postal code
country_code
string
Required
Only US
is allowed for now.
signatory
string
Optional
Signer of the check. Maximum length: 30
characters.
Request
curl 'https://api.column.com/transfers/checks/issue' \
-XPOST \
-u :<YOUR API KEY> \
-d bank_account_id="<bank_account_id>" \
-d positive_pay_amount=100000 \
-d currency_code="USD" \
-d payee_name="Oliver Hockey"
Response
{
"account_number_id": "acno_2Nc1pSb55eCJ7YxQnzCVis9OXrv",
"back_image": null,
"bank_account_id": "bacc_2Nc1pNdlOtyKM0SzfemCyHsWUn5",
"check_number": 1003,
"created_at": "2023-06-16T18:09:00.61936799Z",
"currency_code": "USD",
"delivered_by_column": false,
"delivery_status": null,
"deposited_amount": null,
"deposited_at": null,
"description": null,
"external_routing_number": null,
"first_return_at": null,
"front_image": null,
"id": "chkt_2RIYDHnZCWKEYyU12qhTpjsVmzy",
"idempotency_key": null,
"is_preview_pdf_available": false,
"issued_at": "2023-06-16T18:09:00.653492083Z",
"manual_review_at": null,
"memo": null,
"message": null,
"micr_line": {
"amount_field": "100000",
"auxiliary_on_us": "1003",
"external_processing_code": "",
"on_us": "199175569013840",
"payor_bank_routing_number": "121145307"
},
"payee_address": null,
"payee_name": "Oliver Hockey",
"pending_deposit_at": null,
"pending_first_return_at": null,
"pending_stop_at": null,
"pending_user_initiated_return_at": null,
"positive_pay_amount": "100000",
"reclear_at": null,
"rejected_at": null,
"second_return_at": null,
"settled_at": null,
"status": "issued",
"stopped_at": null,
"type": "debit",
"updated_at": "2023-06-16T18:09:00.654Z",
"user_initiated_return_submitted_at": null,
"user_initiated_returned_at": null,
"user_initiated_return_dishonored_at": null
}
Get a check preview PDF for issued transfer
GET
/transfers/checks/<check_transfer_id>/preview-pdf
Get a preview PDF for a transfer. Only available for check delivered by Column
path parameters
check_transfer_id
string
Required
Request
curl 'https://api.column.com/transfers/checks/<check_transfer_id>/preview-pdf' \
-u :<YOUR API KEY>
Response
PDF Binary
Get a check transfer
GET
/transfers/checks/<check_transfer_id>
Retrieve a single check transfer by its ID.
path parameters
check_transfer_id
string
Required
Request
curl 'https://api.column.com/transfers/checks/<check_transfer_id>' \
-u :<YOUR API KEY>
Response
{
"account_number_id": "acno_2Nc1pSb55eCJ7YxQnzCVis9OXrv",
"back_image": null,
"bank_account_id": "bacc_2Nc1pNdlOtyKM0SzfemCyHsWUn5",
"check_number": 1003,
"created_at": "2023-06-16T18:09:00.61936799Z",
"currency_code": "USD",
"delivered_by_column": false,
"delivery_status": null,
"deposited_amount": null,
"deposited_amount": 100000,
"deposited_at": null,
"description": null,
"external_routing_number": null,
"first_return_at": null,
"front_image": null,
"id": "chkt_2RIYDHnZCWKEYyU12qhTpjsVmzy",
"idempotency_key": null,
"is_preview_pdf_available": false,
"issued_at": "2023-06-16T18:09:00.653492083Z",
"manual_review_at": null,
"memo": null,
"message": null,
"micr_line": {
"amount_field": "100000",
"auxiliary_on_us": "1003",
"external_processing_code": "",
"on_us": "199175569013840",
"payor_bank_routing_number": "121145307"
},
"payee_address": null,
"payee_name": "Olive Column",
"pending_deposit_at": null,
"pending_first_return_at": null,
"pending_stop_at": null,
"pending_user_initiated_return_at": null,
"positive_pay_amount": 100000,
"reclear_at": null,
"rejected_at": null,
"second_return_at": null,
"settled_at": null,
"status": "issued",
"stopped_at": null,
"type": "debit",
"updated_at": "2023-06-16T18:09:00.654Z",
"user_initiated_return_submitted_at": null,
"user_initiated_returned_at": null,
"user_initiated_return_dishonored_at": null
}
List all check transfer
GET
/transfers/checks
Retrieve all check transfers on your platform.
query parameters
limit
int32
Optional
A limit of the number of objects to be returned, between 1
and 100
. The default is 10
.
starting_after
string
Optional
A cursor for use in pagination. starting_after
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with foo_ZXhhbXBsZQo
, your subsequent call can include starting_after=foo_ZXhhbXBsZQo
in order to fetch the next page of the list.
ending_before
string
Optional
A cursor for use in pagination. ending_before
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, starting with foo_ZXhhbXBsZQo=
, your subsequent call can include ending_before=foo_ZXhhbXBsZQo=
in order to fetch the previous page of the list.
created.gt
date-time
Optional
Return results where the specified time field is greater than this value.
created.gte
date-time
Optional
Return results where the specified time field is greater than or equal to this value.
created.lt
date-time
Optional
Return results where the specified time field is less than this value.
created.lte
date-time
Optional
Return results where the specified time field is less than or equal to this value.
Request
curl 'https://api.column.com/transfers/checks' \
-u :<YOUR API KEY>
Response
{
"transfers":[
{
"account_number_id": "acno_2Nc1pSb55eCJ7YxQnzCVis9OXrv",
"back_image": null,
"bank_account_id": "bacc_2Nc1pNdlOtyKM0SzfemCyHsWUn5",
"check_number": 1003,
"created_at": "2023-06-16T18:09:00.61936799Z",
"currency_code": "USD",
"delivered_by_column": false,
"delivery_status": null,
"deposited_amount": null,
"deposited_at": null,
"description": null,
"external_routing_number": null,
"first_return_at": null,
"front_image": null,
"id": "chkt_2RIYDHnZCWKEYyU12qhTpjsVmzy",
"idempotency_key": null,
"is_preview_pdf_available": false,
"issued_at": "2023-06-16T18:09:00.653492083Z",
"manual_review_at": null,
"memo": null,
"message": null,
"micr_line": {
"amount_field": "100000",
"auxiliary_on_us": "1003",
"external_processing_code": "",
"on_us": "199175569013840",
"payor_bank_routing_number": "121145307"
},
"payee_address": null,
"payee_name": "Olive Column",
"pending_deposit_at": null,
"pending_first_return_at": null,
"pending_stop_at": null,
"pending_user_initiated_return_at": null,
"positive_pay_amount": "100000",
"reclear_at": null,
"rejected_at": null,
"second_return_at": null,
"settled_at": null,
"status": "issued",
"stopped_at": null,
"type": "debit",
"updated_at": "2023-06-16T18:09:00.654Z",
"user_initiated_return_submitted_at": null,
"user_initiated_returned_at": null,
"user_initiated_return_dishonored_at": null
}
]
"has_more": true
}
Stop a check transfer
POST
/transfers/checks/<check_transfer_id>/stop-payment
Create a stop payment on a single check transfer by its ID. A check can only be stopped if it is of type debit and is in issued
or manual_review
status. A stopped check will move into a pending_stop
status with a pending_stop_at
timestamp until funds are released, at which point the status will be stopped
and the stopped_at
timestamp will be set.
path parameters
check_transfer_id
string
Required
Request
curl 'https://api.column.com/transfers/checks/<check_transfer_id>/stop-payment' \
-XPOST \
-u :<YOUR API KEY>
Response
{
"account_number_id": "acno_2Nc1pSb55eCJ7YxQnzCVis9OXrv",
"back_image": null,
"bank_account_id": "bacc_2Nc1pNdlOtyKM0SzfemCyHsWUn5",
"check_number": 1003,
"created_at": "2023-06-16T18:09:00.61936799Z",
"currency_code": "USD",
"delivered_by_column": false,
"delivery_status": null,
"deposited_amount": null,
"deposited_at": null,
"description": null,
"external_routing_number": null,
"first_return_at": null,
"front_image": null,
"id": "chkt_2RIYDHnZCWKEYyU12qhTpjsVmzy",
"idempotency_key": null,
"is_preview_pdf_available": false,
"issued_at": "2023-06-16T18:09:00.653492083Z",
"manual_review_at": null,
"memo": null,
"message": null,
"micr_line": {
"amount_field": "100000",
"auxiliary_on_us": "1003",
"external_processing_code": "",
"on_us": "199175569013840",
"payor_bank_routing_number": "121145307"
},
"payee_address": null,
"payee_name": "Olive Column",
"pending_deposit_at": null,
"pending_first_return_at": null,
"pending_stop_at": "2023-06-16T18:09:00.654Z",
"pending_user_initiated_return_at": null,
"positive_pay_amount": "100000",
"reclear_at": null,
"rejected_at": null,
"second_return_at": null,
"settled_at": null,
"status": "pending_stop",
"stopped_at": null,
"type": "debit",
"updated_at": "2023-06-16T18:09:00.654Z",
"user_initiated_return_submitted_at": null,
"user_initiated_returned_at": null,
"user_initiated_return_dishonored_at": null
}
Deposit a check
POST
/transfers/checks/deposit
Deposit a check into a Column bank account.
body parameters
bank_account_id
string
Required
ID of the bank account to which the check will be deposited.
account_number_id
or bank_account_id
is required.
account_number_id
string
Optional
Account number to which the check will be deposited. If no account_number_id
is specified, the default account number on bank_account_id is used.
account_number_id
or bank_account_id
is required.
description
string
Optional
Description of the deposited check visible only in your platform. Maximum length: 255
characters.
deposited_amount
int64
Required
Amount (in cents) of the check that is being deposited.
e.g. $1.75 would be represented by 175
.
currency_code
string
Required
The three-letter currency code defined in ISO 4217. e.g. USD
micr_line
object
Required
The MICR line is the sequence of numbers and characters at the bottom of a check.
amount_field
string
Optional
Amount of the issued check.
auxiliary_on_us
string
Optional
Auxiliary on us. This field is provided by the issuing bank and most commonly used for a check number. In many cases, auxiliary_on_us will be the string before a routing number in the MICR line.
external_processing_code
string
Optional
External processing code.
payor_bank_routing_number
string
Required
Payor bank routing number.
on_us
string
Required
On us. This field is provided by the issuing bank and most commonly contains both check number and account number. In many cases, on-us will be the string after a routing number in the MICR line.
image_front
string
Required
Base64 encoded image of the front of the check. The image should be cropped along the edges of the check and oriented correctly.
image_back
string
Required
Base64 encoded image of the back of the check. The image should be cropped along the edges of the check and oriented correctly.
Request
curl 'https://api.column.com/transfers/checks/deposit' \
-XPOST \
-u :<YOUR API KEY> \
-d bank_account_id="<bank_account_id>" \
-d deposited_amount=50000 \
-d currency_code="USD" \
-d micr_line[auxiliary_on_us]="1" \
-d micr_line[on_us]="1" \
-d micr_line[payor_bank_routing_number]="123456789" \
-d image_front="<base64_encoded_image>" \
-d image_back="<base64_encoded_image>"
Response
{
"account_number_id": "acno_25nacNsLD8qLI1Vc6x67sxFU27c",
"back_image":"<base 64 encoded string>"
"bank_account_id": "bacc_25nVQr05nZybpyEzw8j0wV6VRUh",
"check_number": "1001",
"created_at": "2022-03-02T00:05:54Z",
"currency_code": "USD",
"delivered_by_column": false,
"delivery_status": null,
"deposited_amount": "100000",
"deposited_at": "2022-03-02T00:05:54Z",
"description": "deposited check transfer",
"external_routing_number": "<payor bank routing number>",
"first_return_at": null,
"front_image":"<base 64 encoded string>"
"id": "chkt_25o3LGGbxLjpabTm6zHquAM1ti2",
"idempotency_key": "",
"is_preview_pdf_available": false,
"issued_at": null,
"manual_review_at": null,
"memo": null,
"message": null,
"micr_line": {
"amount_field": "100000",
"auxiliary_on_us": "1001",
"external_processing_code": "",
"payor_bank_routing_number": "322271627",
"on_us": "12345678910"
},
"payee_address": null,
"payee_name": "Olive Column",
"pending_deposit_at": "2022-03-02T00:05:54Z",
"pending_first_return_at": null,
"pending_stop_at": null,
"pending_user_initiated_return_at": null,
"positive_pay_amount": null,
"reclear_at": null,
"rejected_at": null,
"second_return_at": null,
"settled_at": "2022-03-02T00:05:54Z",
"status": "settled",
"stopped_at": null,
"deposited_amount": 50000,
"rejected_at": null,
"status": "pending_deposit",
"type": "credit",
"updated_at": "2022-03-02T00:05:54Z",
"user_initiated_return_submitted_at": null,
"user_initiated_returned_at": null,
"user_initiated_return_dishonored_at": null
}
Capture front of check
POST
/transfers/checks/image/front
Preprocess an image of the front of a check. The response is going to include the parsed MICR Line data, deposit amount, and a processed TIFF image that conforms to the ICL file standard. The response fields are in the same format as the input of the check deposit API.
We recommend placing the check on a darker background, such as a darker shade if the check paper is white. The check itself should occupy the majority of the image. Additionally, we suggest using a higher DPI to ensure that the characters are easily recognizable. It is also advisable to correctly orient the check.
Note that the MICR and amount parsing is still in Beta. We recommend you validate parsed data with the user before submitting a check deposit.
body parameters
file
file
Required
An image file to upload (maximum size: 16MB
). Most common image types are supported (PNG, JPEG, HEIC, TIFF, etc.). The file should follow the specifications of RFC 2388 for multipart/form-data
protocol.
Request
curl 'https://api.column.com/transfers/checks/image/front' \
-u :<YOUR API KEY> \
-F file=@<YOUR FILE> \
Response
{
"image_front": "<base64_encoded_tiff_image>"
"micr_line": {
"amount_field": "50000",
"auxiliary_on_us": "1",
"on_us": "string",
"payor_bank_routing_number": "string"
},
"micr_line_confidence": 0.99,
"deposited_amount": "50000",
"deposited_amount_confidence": 0.99,
"receiver_name": "string",
"receiver_name_confidence": 0.99,
"receiver_address": "string",
"receiver_address_confidence": 0.99,
}
Capture back of check
POST
/transfers/checks/image/back
Preprocess an image of the back of a check. The response is going to include a processed TIFF image that conforms to the ICL file standard. The response fields are in the same format as the input of the check deposit API.
We recommend placing the check on a darker background, such as a darker shade if the check paper is white. The check itself should occupy the majority of the image. Additionally, we suggest using a higher DPI to ensure that the characters are easily recognizable. It is also advisable to correctly orient the check.
Note that the MICR and amount parsing is still in Beta. We recommend you validate parsed data with the user before submitting a check deposit.
body parameters
file
file
Required
An image file to upload (maximum size: 16MB
). Most common image types are supported (PNG, JPEG, HEIC, TIFF, etc.). The file should follow the specifications of RFC 2388 for multipart/form-data
protocol.
Request
curl 'https://api.column.com/transfers/checks/image/back' \
-u :<YOUR API KEY> \
-F file=@<YOUR FILE> \
Response
{
"image_back": "<base64_encoded_tiff_image>"
}
Check return object
The check return object represents the current state of a single check return initiated by or received by Column. The check return object exposes all relevant information about the check return to developers. Read about more about check returns here.
object parameters
check_transfer_id
string
ID of the check transfer that has been returned.
created_at
string
Date (format: YYYY-MM-DD
) on which the check return was created.
id
string
The unique id of the check return object.
return_reason
string
The reason for which the check was returned.
status
string
The current status of the check return. Possible statuses are scheduled
andprocessed
.
updated_at
string
The timestamp at which the check return was last updated.
Check Return Object
{
"check_transfer_id": "chkt_2Mk9STaPIGvIPJFy2DTBmcQhGWr",
"created_at": "2023-03-08T19:22:01Z",
"id": "chrt_2MkEkAVdv0Cc80AJAzgq5QxXEk5",
"return_reason": "Q",
"status": "processed",
"updated_at": "2023-03-08T20:00:33Z"
}
Create a check return
POST
/transfers/checks/<check_transfer_id>/return
Submit a request to return an incoming check transfer received from an ODFI. At most only one return request can be submitted for each check. You can read more about check returns here.
path parameters
check_transfer_id
string
Required
ID of the check transfer you're looking up.
body parameters
return_reason
string
Required
Return reason for a manual return. Only Q
and N
are allowed as manual return reasons.
Request
curl 'https://api.column.com/transfers/checks/<check_transfer_id>/return' \
-XPOST \
-u :<YOUR API KEY>
Response
{}
Get check transfer returns
GET
/transfers/checks/<check_transfer_id>/returns
Retrieve all returns for a check transfer by the check transfer ID.
path parameters
check_transfer_id
string
Required
Request
curl 'https://api.column.com/transfers/checks/<check_transfer_id>/returns' \
-u :<YOUR API KEY>
Response
{
"returns": [
{
"check_transfer_id": "chkt_2Mk9STaPIGvIPJFy2DTBmcQhGWr",
"created_at": "2023-03-08T19:22:01Z",
"id": "chrt_2MkEkAVdv0Cc80AJAzgq5QxXEk5",
"return_reason": "Q",
"status": "processed",
"updated_at": "2023-03-08T20:00:33Z"
}
],
"has_more": false
}
List all check returns
GET
/transfers/checks/returns
Retrieve the return processing details of all check returns under your platform, including returns created by you and other financial institutions.
query parameters
limit
int32
Optional
A limit of the number of objects to be returned, between 1
and 100
. The default is 10
.
starting_after
string
Optional
A cursor for use in pagination. starting_after
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with foo_ZXhhbXBsZQo
, your subsequent call can include starting_after=foo_ZXhhbXBsZQo
in order to fetch the next page of the list.
ending_before
string
Optional
A cursor for use in pagination. ending_before
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, starting with foo_ZXhhbXBsZQo=
, your subsequent call can include ending_before=foo_ZXhhbXBsZQo=
in order to fetch the previous page of the list.
created.gt
date-time
Optional
Return results where the specified time field is greater than this value.
created.gte
date-time
Optional
Return results where the specified time field is greater than or equal to this value.
created.lt
date-time
Optional
Return results where the specified time field is less than this value.
created.lte
date-time
Optional
Return results where the specified time field is less than or equal to this value.
Request
curl 'https://api.column.com/transfers/checks/returns' \
-u :<YOUR API KEY>
Response
{
"returns": [
{
"check_transfer_id": "chkt_2NcEI6o0cH76Lk5HA0YmKyCeFiJ",
"created_at": "2023-03-29T00:00:13Z",
"id": "chrt_2NfH37IJo3cDiodHYlIcKGHhaQL",
"return_reason": "A",
"status": "processed",
"updated_at": "2023-03-29T00:00:29Z"
},
{
"check_transfer_id": "chkt_2NcKdWa6FQZ9wZ8ZNX8gijPjGXU",
"created_at": "2023-03-27T23:00:17Z",
"id": "chrt_2NcKdYxShVu8tl8DAxNPljMbdeG",
"return_reason": "Y",
"status": "processed",
"updated_at": "2023-03-28T00:00:31Z"
},
],
"has_more": false
}
Receive an ACH Credit
POST
/simulate/receive-ach-credit
Simulates an incoming ACH Credit transfer to an account for the amount specified
To more accurately represent a production environment, we process incoming ACH transfers every hour. You will not see the effects of an incoming ACH transfer till the ACH is processed.
body parameters
destination_account_number_id
string
Required
Identifier for the account to credit or debit
amount
string
Required
Amount (in cents) to credit or debit the account
e.g. $1.75 would be represented by 175
currency_code
string
Required
The three-letter currency code defined in ISO 4217. e.g. USD
Request
curl 'https://api.column.com/simulate/receive-ach-credit' \
-XPOST \
-u :<YOUR API KEY> \
-d destination_account_number_id="<destination_account_number_id>" \
-d amount="100000" \
-d currency_code="USD"
Response
{}
Receive an ACH Debit
POST
/simulate/receive-ach-debit
Simulates an incoming ACH Debit transfer from an account for the amount specified.
To more accurately represent a production environment, we process incoming ACH transfers every hour. You will not see the effects of an incoming ACH transfer till the ACH is processed.
body parameters
destination_account_number_id
string
Required
Identifier for the account to credit or debit
amount
string
Required
Amount (in cents) to credit or debit the account
e.g. $1.75 would be represented by 175
currency_code
string
Required
The three-letter currency code defined in ISO 4217. e.g. USD
Request
curl 'https://api.column.com/simulate/receive-ach-debit' \
-XPOST \
-u :<YOUR API KEY> \
-d destination_account_number_id="<destination_account_number_id>" \
-d amount="100000" \
-d currency_code="USD"
Response
{}
Receive a Wire Transfer
POST
/simulate/receive-wire
Simulates an incoming wire transfer to an account for the amount specified.
We recommend using this API to set a balance on your account in the sandbox environment. This API is always enabled, and is not affected by the operating hours of the sandbox FedWire system.
body parameters
destination_account_number_id
string
Required
Identifier for the account to credit
amount
string
Required
Amount (in cents) to credit the account
e.g. $1.75 would be represented by 175
currency_code
string
Required
The three-letter currency code defined in ISO 4217. e.g. USD
Request
curl 'https://api.column.com/simulate/receive-wire' \
-XPOST \
-u :<YOUR API KEY> \
-d destination_account_number_id="<destination_account_number_id>" \
-d amount="100000" \
-d currency_code="USD"
Response
{}
Receive an international wire
POST
/simulate/receive-international-wire
Simulates an incoming international wire transfer to an account for the amount specified.
body parameters
destination_account_number_id
string
Required
Identifier for the account to credit
amount
string
Required
Amount (in the smallest unit of the currency) to credit the account.
e.g. CNY 1.75 would be represented by 175
currency_code
string
Required
The three-letter currency code defined in ISO 4217. e.g. CNY
Request
curl 'https://api.column.com/simulate/receive-international-wire' \
-XPOST \
-u :<YOUR API KEY> \
-d destination_account_number_id="<destination_account_number_id>" \
-d amount="100000" \
-d currency_code="CNY"
Response
{}
Receive a wire drawdown request
POST
/simulate/receive-wire-drawdown-request
Simulates an incoming wire drawdown request into the specified account number id.
body parameters
account_number_id
string
Required
Identifier for Column bank account which the drawdown request will be processed from
amount
string
Required
Amount (in cents) specified in the drawdown request
e.g. $1.75 would be represented by 175
currency_code
string
Required
The three-letter currency code defined in ISO 4217. e.g. USD
Request
curl 'https://api.column.com/simulate/receive-wire-drawdown-request' \
-XPOST \
-u :<YOUR API KEY> \
-d account_number_id="<account_number_id>" \
-d amount="100000" \
-d currency_code="USD"
Response
{}
Receive a Realtime Transfer
POST
/simulate/transfers/realtime/receive-credit
Simulates an incoming realtime transfer to an account for the amount specified.
body parameters
destination_account_number_id
string
Required
Identifier for the account to credit
amount
string
Required
Amount (in cents) to credit the account
e.g. $1.75 would be represented by 175
currency_code
string
Required
The three-letter currency code defined in ISO 4217. e.g. USD
Request
curl 'https://api.column.com/simulate/transfers/realtime/receive-credit' \
-X POST \
-u :<YOUR API KEY> \
-d destination_account_number_id="<destination_account_number_id>" \
-d amount="100000" \
-d currency_code="USD"
Response
{}
Settle ACH transfer
POST
/simulate/transfers/ach/settle
Forces the settlement of an outgoing ACH transfer, regardless of the operating hours of the Sandbox Fed
body parameters
ach_transfer_id
string
Required
ID of the outgoing transfer to force a settlement
Request
curl 'https://api.column.com/simulate/transfers/ach/settle' \
-XPOST \
-u :<YOUR API KEY> \
-d ach_transfer_id="<ach_transfer_id>"
Response
{}
Settle wire transfer
POST
/simulate/transfers/wire/settle
Forces the submission and settlement of an outgoing Wire transfer, regardless of the operating hours of the Sandbox Fed.
The wire message should move from PENDING_SUBMISSION
to COMPLETED
after this API call
body parameters
wire_transfer_id
string
Required
ID of the outgoing transfer to force a settlement
Request
curl 'https://api.column.com/simulate/transfers/wire/settle' \
-XPOST \
-u :<YOUR API KEY> \
-d wire_transfer_id="<wire_transfer_id>"
Response
{}
Settle check deposit
POST
/simulate/transfers/checks/settle
Forces the settlement of a deposited check. After a check is deposited in sandbox, it is going to move from a pending_deposit
state to a deposited
state within an hour to simulate check forwarding to the Fed. This endpoint allows you to force
settlement after the check is transitioned to a deposited
state. This will transition the transfer to settled
and make
funds available immediately.
body parameters
check_transfer_id
string
Required
ID of the check transfer
Request
curl 'https://api.column.com/simulate/transfers/checks/settle' \
-XPOST \
-u :<YOUR API KEY> \
-d check_transfer_id="<wire_transfer_id>"
Response
{}
Deposit an issued check
POST
/simulate/deposit-issued-check
Simulates the deposit of an issued check. This API is always enabled, and is not affected by the operating hours of the sandbox FedWire system.
body parameters
check_transfer_id
string
Required
Identifier for the issued check transfer to settle.
Request
curl 'https://api.column.com/simulate/deposit-issued-check' \
-XPOST \
-u :<YOUR API KEY> \
-d check_transfer_id="<check_transfer_id>" \
Response
{}
List all transfers
GET
/transfers
Returns all ACH, Wire, and Book transfers, both incoming and outgoing. Transfers are sorted from newest to oldest (transfers created within the same second are sorted alphabetically by transfer ID). The transfer type is specified in the type
field, which is one of ach_credit
, ach_debit
, wire
, swift
, check_debit
, and book
.
The is_incoming
field is used to flag incoming transfers. The sender is the originator of the transfer for ach_debit
, ach_credit
, wire
, and swift
transfers. For incoming transfers, external_source
and receiver_internal_account
will be returned. For outgoing transfers, external_source
and sender_internal_account
will be returned.
query parameters
limit
int32
Optional
A limit of the number of objects to be returned, between 1
and 100
. The default is 10
.
starting_after
string
Optional
A cursor for use in pagination. starting_after
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with foo_ZXhhbXBsZQo
, your subsequent call can include starting_after=foo_ZXhhbXBsZQo
in order to fetch the next page of the list.
ending_before
string
Optional
A cursor for use in pagination. ending_before
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, starting with foo_ZXhhbXBsZQo=
, your subsequent call can include ending_before=foo_ZXhhbXBsZQo=
in order to fetch the previous page of the list.
type
string
Optional
Return results of the given transfer type (accepts multiple values, comma separated)
Possible enum values:
ach_debit
ach_credit
book
check
swift
wire
bank_account_id
string
Optional
Return results where this bank account is either sender or receiver of the transfer.
sender_bank_account_id
string
Optional
Return results where this bank account is a sender of the transfer.
receiver_bank_account_id
string
Optional
Return results where this bank account is a receiver of the transfer.
account_number_id
string
Optional
Return results where this account number is either sender or receiver of the transfer.
sender_account_number_id
string
Optional
Return results where this account number is a sender of the transfer.
receiver_account_number_id
string
Optional
Return results where this account number is a receiver of the transfer.
counterparty_id
string
Optional
Return results associated with this counterparty.
transfer_id
string
Optional
Return results associated with this transfer_id (of any type)
description
string
Optional
Return results with transfers matching the description.
amount
string
Optional
Return results with transfers matching the amount.
amount_gt
int
Optional
Return results with transfers that have the amount greater than the value (in smallest currency unit)
amount_lt
int
Optional
Return results with transfers that have the amount lesser than the value (in smallest currency unit)
amount_gte
int
Optional
Return results that have the amount greater or equal than the value (in smallest currency unit)
amount_lte
int
Optional
Return results with transfers that have the amount lesser than or equal the value (in smallest currency unit)
created_at_gt
date / time
Optional
Return results that were created after the date / time specified. Example: 2023-12-01T00:00:00-00:00
created_at_lt
date / time
Optional
Return results that were created before the date / time specified. Example: 2023-12-01T00:00:00-00:00
created_at_gte
date / time
Optional
Return results that were created after or equal to the date / time specified. Example: 2023-12-01T00:00:00-00:00
created_at_lte
date / time
Optional
Return results that were created after or equal to the date / time specified. Example: 2023-12-01T00:00:00-00:00
is_incoming
boolean
Optional
Return transfers that is either incoming or outgoing.
status
string
Optional
Return results with this status (accepts multiple values, comma separated).
Possible enum values:
canceled
completed
deposited
failed
first_return
hold
initiated
issued
manual_review
manual_review_approved
pending_deposit
pending_first_return
pending_reclear
pending_return
pending_second_return
pending_stop
pending_submission
pending_user_initiated_return
recleared
rejected
return_contested
return_dishonored
returned
scheduled
second_return
settled
stopped
submitted
user_initiated_returned
user_initiated_return_submitted
user_initiated_return_dishonored
Request
curl 'https://api.column.com/transfers' \
-u :<YOUR API KEY>
Response
{
"transfers": [
{
"id": "string",
"created_at": "2021-11-29T21:16:16.779Z",
"updated_at": "2021-11-29T21:16:16.779Z",
"completed_at": "2021-11-29T21:16:16.779Z",
"status": "string",
"type": "string",
"amount": int64,
"currency_code": "string",
"is_incoming": true,
"idempotency_key": "string",
"description": "string",
"sender_internal_account": {
"bank_account_id": "string",
"account_number_id": "string"
},
"external_source": {
"bank_name": "string",
"sender_name": "string"
},
"receiver_internal_account": {
"bank_account_id": "string",
"account_number_id": "string"
},
"external_destination": {
"counterparty_id": "string"
}
}
],
"has_more": true
"total_results_count": 100,
}
Event object
The event object is a snapshot of a particular data object (ACH, wire, book, return...etc) in time. An event object will be created each time a data object is created, or changes state. For example, you can use events to track state changes of a particular transfer over time - like an ACH transfer that has been initiated, submitted, settled, or returned. Read about more about events here.
object parameters
created_at
string
The timestamp at which the event was emitted.
data
object
The object instance that triggered the event to be emitted. For example, on an ach.*
event, this will be the ACH object.
id
string
The unique id of the object
type
string
The type of event which was emitted. See Events and Webhooks for more information.
Event object
{
{
"created_at": "2022-02-21T17:19:41Z",
"data": {
<returned object>
},
"id": "evnt_25Qex2OLy3qrssrKvds7df4D1ej",
"type": "book.transfer.completed"
}
}
List all events
GET
/events
Lists all events, inclusive of events sent via webhooks.
query parameters
created.gt
date-time
Optional
Return results where the specified time field is greater than this value.
created.gte
date-time
Optional
Return results where the specified time field is greater than or equal to this value.
created.lt
date-time
Optional
Return results where the specified time field is less than this value.
created.lte
date-time
Optional
Return results where the specified time field is less than or equal to this value.
ending_before
string
Optional
A cursor for use in pagination. ending_before
is an event ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, starting with evnt_id1
, your subsequent call can include ending_before=evnt_id1
in order to fetch the previous page of the list.
limit
int32
Optional
A limit of the number of objects to be returned. The default is 20
.
object_ids
array of strings
Optional
Filter events by their associated objects (e.g., wire transfer IDs, bank account IDs, etc.). Format: object_ids=id_1&object_ids=id_2&object_ids=id_3...
.
starting_after
string
Optional
A cursor for use in pagination. starting_after
is an event ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with evnt_id2
, your subsequent call can include starting_after=evnt_id2
in order to fetch the next page of the list.
types
array of strings
Optional
The types of events you want to retrieve (format: types=type_1&types=type_2&types=type_3...
). See all events here.
Request
curl 'https://api.column.com/events?types=type_1&types=type_2&types=type_3' \
-u :<YOUR API KEY>
Response
{
"events": [
{
"id": "string",
"created_at": "2021-11-29T21:26:42.872Z",
"type": "string",
"data": {
"type_url": "string",
"value": "string"
}
}
],
"has_more": false
}
List all webhook events
GET
/events/webhook
Lists just the events that resulted in webhooks. Useful for reconciling webhooks.
query parameters
created.gt
date-time
Optional
Return results where the specified time field is greater than this value.
created.gte
date-time
Optional
Return results where the specified time field is greater than or equal to this value.
created.lt
date-time
Optional
Return results where the specified time field is less than this value.
created.lte
date-time
Optional
Return results where the specified time field is less than or equal to this value.
ending_before
string
Optional
A cursor for use in pagination. ending_before
is an event ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, starting with evnt_id1
, your subsequent call can include ending_before=evnt_id1
in order to fetch the previous page of the list.
limit
int32
Optional
A limit of the number of objects to be returned. The default is 20
.
object_ids
array of strings
Optional
Filter events by their associated objects (e.g., wire transfer IDs, bank account IDs, etc.). Format: object_ids=id_1&object_ids=id_2&object_ids=id_3...
.
starting_after
string
Optional
A cursor for use in pagination. starting_after
is an event ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with evnt_id2
, your subsequent call can include starting_after=evnt_id2
in order to fetch the next page of the list.
types
array of strings
Optional
The types of events you want to retrieve (format: types=type_1&types=type_2&types=type_3...
). See all events here.
Request
curl 'https://api.column.com/events/webhook' \
-u :<YOUR API KEY>
Response
{
"events": [
{
"id": "string",
"created_at": "2021-11-29T21:26:42.872Z",
"type": "string",
"data": {
"type_url": "string",
"value": "string"
}
}
],
"has_more": false
}
Get an event by ID
GET
/events/<id>
Retrieve an event
by its id
path parameters
id
string
Required
Request
curl 'https://api.column.com/events/<event_id>' \
-u :<YOUR API KEY>
Response
{
"id": "string",
"created_at": "2021-11-29T21:29:34.023Z",
"type": "string",
"data": {
"type_url": "string",
"value": "string"
}
}
Document object
Document objects are a pointer to documents that are created or stored on Column. There are two main types of documents: Documents you upload to Column which support KYC/KYB verification for entities. And report documents generated by Column, which you can download.
object parameters
checksum
string
The SHA-256 checksum of the uploaded document.
created_at
string
Timestamp at which the document was created in the Column system.
description
string
Description of the document provided when the document was created.
id
string
The unique id of this object.
size
integer
type
string
The type of document. Can be bank_transaction_report
, bank_summary_report
, identity_license
, identity_passport
, or identity_utility
.
updated_at
string
The timestamp the document was updated.
url
string
URL to download the document. Expire after 60 seconds. Note: When retrieving this URL with curl in terminal, some characters become encoded and copy and pasting the URL will throw an error in the browser. Try testing this out using POSTMAN instead.
Document object
{
"checksum": "f58b9e7dda62420b6c016ed71ff5d6b224437ec74ace972a333622e1de8bbfdf",
"created_at": "2022-03-03T22:47:33Z",
"description": "",
"id": "docu_25tY3k5619LebLZNk4EcN1a9Zka",
"size": 422989,
"type": "identity_license",
"updated_at": "2022-03-03T22:47:33Z",
"url": "https://bucket.s3.us-west-2.amazonaws.com/..."
}
Upload a document
POST
/documents
To upload a file to Column, you will need to send a request with Content-Type: multipart/form-data
. The request should contain the file you would like to upload, as well as other metadata.
body parameters
file
file
Required
A file to upload (maximum size: 16MB
). The file should follow the specifications of RFC 2388 for multipart/form-data
protocol.
type
string
Required
Type of the document. Possible enum values:
identity_license
: a document to verify the identity of an account owner (e.g., driver licenses, state ID cards, Articles of Incorporation, etc.)identity_passport
: the passport of an account owner to verify the identityidentity_utility
: an utility bill of an account ownercheck_attachment
: an attachment to a mailed check. PDFs, HTML, PNGs, and JPGs are allowed as attachments. For PDFs, PNGs, and JPGs, all pages must be sized at 8.5"x11" at 300 DPI. If HTML is supplied, it will be rendered and trimmed to fit as many 8.5"x11" pages as necessary. If a PDF is provided, it must be 6 pages or fewer. The attachment will be printed double-sided in black and white and included in the envelope after the check page. The ID can be used as `attachment_document_id` in the check issuing request.
description
string
Optional
Description of the document. Maximum length: 127
characters.
Request
curl 'https://api.column.com/documents' \
-u :<YOUR API KEY> \
-F file=@<YOUR FILE> \
-F type="identity_license"
Response
{
"checksum": "f58b9e7dda62420b6c016ed71ff5d6b224437ec74ace972a333622e1de8bbfdf",
"created_at": "2022-03-03T22:47:33Z",
"description": "",
"id": "docu_25tY3k5619LebLZNk4EcN1a9Zka",
"size": 422989,
"type": "identity_license",
"updated_at": "2022-03-03T22:47:33Z",
"url": "https://bucket.s3.us-west-2.amazonaws.com/..."
}
Get a document
GET
/documents/<document_id>
Retrieves the details of an existing document.
path parameters
document_id
string
Required
ID of the document you're requesting
Request
curl 'https://api.column.com/documents/<document_id>' \
-u :<YOUR API KEY>'
Response
{
"checksum": "f58b9e7dda62420b6c016ed71ff5d6b224437ec74ace972a333622e1de8bbfdf",
"created_at": "2022-03-03T22:47:33Z",
"description": "",
"id": "docu_25tY3k5619LebLZNk4EcN1a9Zka",
"size": 422989,
"type": "identity_license",
"updated_at": "2022-03-03T22:47:33Z",
"url": "https://bucket.s3.us-west-2.amazonaws.com/..."
}
Settlement Report object
The settlement report object is a pointer to a settlement report generated by Column. Settlement reports contain data about historical bank account balances, and historical bank account transactions (book transfers, ACH, and wires). Read more about reports here.
object parameters
columns
array
List of columns in the settlement report. Refer to Reporting Guidance for more details.
completed_at
string
The timestamp the settlement report was generated successfully.
created_at
string
The timestamp the settlement report was scheduled.
csv_document_id
string
Document ID to download the CSV format of the settlement report.
from_date
string
Starting date (inclusive, from the beginning of from_date
in time_zone
) of transactions included in the settlement report.
id
string
Unique identifier for the object.
initiated_at
string
The timestamp the settlement report was initiated to be processed.
json_document_id
string
Document ID to download the JSON format of the settlement report.
parquet_document_id
string
Document ID to download the Parquet format of the settlement report.
row_count
int32
Total number of records in the settlement report.
status
string
The current status of the report. Can be scheduled
, initiated
, completed
, or failed
.
time_zone
string
Time zone of the settlement report to decide day boundaries. It is a value defined in the IANA TZ database (e.g., America/Los_Angeles
, UTC
, etc.). You can set your platform reporting time zone in Platform Settings on Dashboard.
to_date
string
Ending date (inclusive, up to the end of to_date
in time_zone
) of transactions included in the settlement report.
type
string
Settlement report type. Can be bank_account_summary
, or bank_account_transaction
.
updated_at
string
The timestamp the settlement report was last updated.
Settlement Report object
{
"id": "srpt_27kkUzwpYqt78g3L1DWU7cBRjyL",
"created_at": "2022-04-13T17:38:11Z",
"updated_at": "2022-04-13T17:38:11Z",
"type": "bank_account_transaction",
"status": "completed",
"time_zone": "America/Los_Angeles",
"from_date": "2022-03-02",
"to_date": "2022-03-02",
"initiated_at": "2022-04-13T17:10:15Z",
"completed_at": "2022-04-13T17:11:15Z",
"row_count": 666,
"columns": [
"effective_at",
"effective_at_utc",
"bank_account_id",
"bank_account_type",
"account_number_id",
"entity_id",
"entity_name",
"entity_type",
"transaction_id",
"transaction_type",
"currency",
"available_amount",
"available_balance",
"pending_amount",
"pending_balance",
"locked_amount",
"locked_balance",
"holding_amount",
"holding_balance"
],
"csv_document_id": "docu_27kh6IxwJjShHV314ig7ioPEwSf",
"json_document_id": "docu_27kh6KhcfYDkPthUdoMSCHD3tv9",
"parquet_document_id": "docu_27kh6LSgYvc1gdcLlpQnAOGzPl6"
}
Schedule a settlement report
POST
/reporting
Schedule a request to generate a settlement report. You must set your platform reporting time zone in Platform Settings on Dashboard. Please refer to our Reporting Guides for more details.
body parameters
from_date
string
Required
Starting date (inclusive) of data included. Earliest available date: 2022-01-01
.
to_date
string
Required
Ending date (inclusive) of data included. Maximum date range: 93
days.
type
string
Required
Settlement report type. Can be bank_account_summary
, or bank_account_transaction
.
Request
curl 'https://api.column.com/reporting' \
-XPOST \
-u :<YOUR API KEY> \
-d type="bank_account_transaction" \
-d from_date="2022-03-01" \
-d to_date="2022-03-31"
Response
{
"id": "srpt_27kigaqHolth6UzjnOohU9tNdSt",
"created_at": "2022-04-13T10:23:16",
"updated_at": "2022-04-13T10:23:16",
"type": "bank_account_transaction",
"status": "scheduled",
"time_zone": "America/Los_Angeles",
"from_date": "2022-03-01",
"to_date": "2022-03-31",
"initiated_at": null,
"completed_at": null,
"row_count": null,
"columns": null,
"csv_document_id": "",
"json_document_id": "",
"parquet_document_id": ""
}
List all settlement reports
GET
/reporting
List all available settlement reports under the platform. Filtered results can be retrieved with extra parameters in the query.
query parameters
from_date
string
Optional
Starting date (inclusive) of data included. Format: YYYY-MM-DD
.
to_date
string
Optional
Ending date (inclusive) of data included. Format: YYYY-MM-DD
.
type
string
Optional
Settlement report type. Can be bank_account_summary
, or bank_account_transaction
.
limit
int32
Optional
A limit of the number of objects to be returned, between 1
and 100
. The default is 10
.
starting_after
string
Optional
A cursor for use in pagination. starting_after
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with foo_ZXhhbXBsZQo
, your subsequent call can include starting_after=foo_ZXhhbXBsZQo
in order to fetch the next page of the list.
ending_before
string
Optional
A cursor for use in pagination. ending_before
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, starting with foo_ZXhhbXBsZQo=
, your subsequent call can include ending_before=foo_ZXhhbXBsZQo=
in order to fetch the previous page of the list.
Request
curl 'https://api.column.com/reporting' \
-u :<YOUR API KEY> \
-d type="bank_account_transaction" \
-d from_date="2022-03-01" \
-d to_date="2022-03-02"
Response
{
"reports": [
{
"id": "srpt_27kigaqHolth6UzjnOohU9tNdSt",
"created_at": "2022-04-13T10:23:16",
"updated_at": "2022-04-13T10:23:16",
"type": "bank_account_transaction",
"status": "scheduled",
"time_zone": "America/Los_Angeles",
"from_date": "2022-03-02",
"to_date": "2022-03-02",
"initiated_at": null,
"completed_at": null,
"row_count": null,
"columns": null,
"csv_document_id": "",
"json_document_id": "",
"parquet_document_id": ""
},
{
"id": "srpt_27kkUwEPiFqmhxLsDgLihgE8pKr",
"created_at": "2022-04-13T17:38:11Z",
"updated_at": "2022-04-13T17:38:11Z",
"type": "bank_account_transaction",
"status": "completed",
"time_zone": "America/Los_Angeles",
"from_date": "2022-03-01",
"to_date": "2022-03-01",
"initiated_at": "2022-04-13T17:10:15Z",
"completed_at": "2022-04-13T17:11:15Z",
"row_count": 888,
"columns": [
"effective_at",
"effective_at_utc",
"bank_account_id",
"bank_account_type",
"account_number_id",
"entity_id",
"entity_name",
"entity_type",
"transaction_id",
"transaction_type",
"currency",
"available_amount",
"available_balance",
"pending_amount",
"pending_balance",
"locked_amount",
"locked_balance",
"holding_amount",
"holding_balance"
],
"csv_document_id": "docu_27kh6MA1yp5d1QT7HorEchZrwab",
"json_document_id": "docu_27kh6MzwxYZGGVa4ZD7GICMY5kd",
"parquet_document_id": "docu_27kh6PbEbYbhMHEDocJ7pYQFQZo"
}
],
"has_more": false
}
Get a settlement report by ID
GET
/reporting/<settlement_report_id>
Get a settlement report by its ID. Please refer to our Reporting Guides for more details.
path parameters
settlement_report_id
string
Required
The ID of the settlement report you are looking up
Request
curl 'https://api.column.com/reporting/srpt_27kigaqHolth6UzjnOohU9tNdSt' \
-u :<YOUR API KEY>
Response
{
"id": "srpt_27kkUzwpYqt78g3L1DWU7cBRjyL",
"created_at": "2022-04-13T17:38:11Z",
"updated_at": "2022-04-13T17:38:11Z",
"type": "bank_account_transaction",
"status": "completed",
"time_zone": "America/Los_Angeles",
"from_date": "2022-03-02",
"to_date": "2022-03-02",
"initiated_at": "2022-04-13T17:10:15Z",
"completed_at": "2022-04-13T17:11:15Z",
"row_count": 666,
"columns": [
"effective_at",
"effective_at_utc",
"bank_account_id",
"bank_account_type",
"account_number_id",
"entity_id",
"entity_name",
"entity_type",
"transaction_id",
"transaction_type",
"currency",
"available_amount",
"available_balance",
"pending_amount",
"pending_balance",
"locked_amount",
"locked_balance",
"holding_amount",
"holding_balance"
],
"csv_document_id": "docu_27kh6IxwJjShHV314ig7ioPEwSf",
"json_document_id": "docu_27kh6KhcfYDkPthUdoMSCHD3tv9",
"parquet_document_id": "docu_27kh6LSgYvc1gdcLlpQnAOGzPl6"
}
Webhook object
The webhook object is the current state of a particular webhook endpoint set up in Column. Webhook endpoints are used to configure URLs used to receive Column events. Read about more about wire transfers here.
object parameters
created_at
string
Date (format: YYYY-MM-DD
) on which the event was emitted.
description
string
A description for this webhook.
enabled_events
array
A list of events and event types which are being sent to this webhook's url.
id
string
The unique id of the object.
is_disabled
boolean
Indicates whether this webhook url is actively receiving events.
secret
string
Secret key which allows you to verify that the event was sent by Column, and not by a third party.
updated_at
string
Timestamp of when this webhook was last updated.
url
string
The https
url that webhooks are going to be delivered to.
e.g. https://yoursite.com/columnevents
Webhook object
{
"created_at": "2022-02-08T18:00:02Z",
"description": "",
"enabled_events": ["*"],
"id": "whep_24q1FvNZuDjwj5w310VaD46oFTD",
"is_disabled": false,
"secret": "whsr_24q1Fwr2aFvAW9BbL5gXXRyS5gR",
"updated_at": "2022-03-03T00:41:04Z",
"url": "https://webhook.site/af74c831-b794-4311-9d49-2678e6faee36"
}
Create a webhook endpoint
POST
/webhook-endpoints
Create a webhook url and description.
This can also be done on the dashboard.
body parameters
enabled_events
array of strings
Required
Enables you to subscribe to certain events. See all events here.
enabled_events
can contain specific event types, or can include wildcard string (e.g., ach.* for all ACH events)
url
string
Required
The https
url that webhooks are going to be delivered to.
e.g. https://yoursite.com/columnevents
description
string
Optional
A description for this webhook.
Request
curl 'https://api.column.com/webhook-endpoints' \
-XPOST \
-u :<YOUR API KEY> \
-d "enabled_events[]"="ach.*" \
-d url="https://docs.column.com"
Response
{
"id": "string",
"created_at": "2021-11-29T21:30:48.799Z",
"updated_at": "2021-11-29T21:30:48.799Z",
"description": "string",
"enabled_events": ["string"],
"secret": "string",
"is_disabled": true,
"url": "string"
}
List all webhook endpoints
GET
/webhook-endpoints
List all webhooks under your developer account
query parameters
limit
int32
Optional
A limit of the number of objects to be returned, between 1
and 100
. The default is 10
.
starting_after
string
Optional
A cursor for use in pagination. starting_after
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, ending with foo_ZXhhbXBsZQo
, your subsequent call can include starting_after=foo_ZXhhbXBsZQo
in order to fetch the next page of the list.
ending_before
string
Optional
A cursor for use in pagination. ending_before
is an ID that defines your place in the list. For instance, if you make a list request and receive 20 objects, starting with foo_ZXhhbXBsZQo=
, your subsequent call can include ending_before=foo_ZXhhbXBsZQo=
in order to fetch the previous page of the list.
Request
curl 'https://api.column.com/webhook-endpoints' \
-u :<YOUR API KEY>
Response
{
"webhook_endpoints": [
{
"id": "string",
"created_at": "2021-11-29T21:35:26.409Z",
"updated_at": "2021-11-29T21:35:26.409Z",
"description": "string",
"enabled_events": ["string"],
"secret": "string",
"is_disabled": true,
"url": "string"
}
]
}
Get a webhook endpoint by ID
GET
/webhook-endpoints/<id>
Retrieve information about the webhook by its id
path parameters
id
string
Required
Request
curl 'https://api.column.com/webhook-endpoints/<webhook_id>' \
-u :<YOUR API KEY>
Response
{
"id": "string",
"created_at": "2021-11-29T21:37:17.367Z",
"updated_at": "2021-11-29T21:37:17.367Z",
"description": "string",
"enabled_events": ["string"],
"secret": "string",
"is_disabled": true,
"url": "string"
}
Update a webhook url
PATCH
/webhook-endpoints/<id>
Update fields on the webhooks
path parameters
id
string
Required
The ID of the webhook endpoint you want to update.
body parameters
enabled_events
array of strings
Required
Enables you to subscribe to certain events. See all events here.
enabled_events
can contain specific event types, or can include wildcard string (e.g., ach.* for all ACH events)
url
string
Required
The https
url that webhooks are going to be delivered to.
e.g. https://yoursite.com/columnevents
description
string
Optional
A description for this webhook.
is_disabled
boolean
Optional
Disable the webhook endpoint if set to true.
Request
curl 'https://api.column.com/webhook-endpoints/<webhook_id>' \
-XPATCH \
-u :<YOUR API KEY> \
-d "enabled_events[]"="ach.*" \
-d url="https://newsdocs.column.com"
Response
{
"id": "string",
"created_at": "2021-11-29T21:38:16.031Z",
"updated_at": "2021-11-29T21:38:16.031Z",
"description": "string",
"enabled_events": ["string"],
"secret": "string",
"is_disabled": true,
"url": "string"
}
Delete a webhook endpoint
DELETE
/webhook-endpoints/<id>
Deletes a webhook
path parameters
id
string
Required
The ID of the webhook endpoint you want to delete.
Request
curl 'https://api.column.com/webhook-endpoints/<webhook_id>' \
-XDELETE \
-u :<YOUR API KEY>
Response
{}
Verify a webhook endpoint
POST
/webhook-endpoints/<id>/verify
Verifies a webhook
path parameters
id
string
Required
The ID of the webhook endpoint you want to verify.
body parameters
event_type
string
Required
Event type. See all events here.
Request
curl 'https://api.column.com/webhook-endpoints/<webhook_id>/verify' \
-XPOST \
-u :<YOUR API KEY> \
-d event_type="ach.outgoing_transfer.initiated"
Response
{
"request_body": "string",
"response_body": "string",
"response_code": 0,
"success": true
}
List all webhook deliveries
GET
/webhook-deliveries/endpoint/<id>
List all the webhook delivery and retry attempts for this endpoint.
path parameters
id
string
Required
query parameters
limit
int32
Optional
A limit of the number of objects to be returned. The default is 20
.
Request
curl 'https://api.column.com/webhook-deliveries/endpoint/<webhook_id>' \
-u :<YOUR API KEY>
Response
{
"webhook_deliveries": [
{
"event": {
"id": "string",
"created_at": "2021-11-29T21:41:05.518Z",
"type": "string",
"data": {
"type_url": "string",
"value": "string"
}
},
"scheduled_at": "2021-11-29T21:41:05.518Z",
"status": "UNKNOWN"
}
]
}
List webhook deliveries by event
GET
/webhook-deliveries/event/<id>
List all the webhook delivery and retry attempts for this event.
path parameters
id
string
Required
Request
curl 'https://api.column.com//webhook-deliveries/event/<event_id>' \
-u :<YOUR API KEY>
Response
{
"webhook_deliveries": [
{
"event": {
"id": "string",
"created_at": "2021-11-29T21:47:18.447Z",
"type": "string",
"data": {
"type_url": "string",
"value": "string"
}
},
"scheduled_at": "2021-11-29T21:47:18.447Z",
"status": "UNKNOWN"
}
]
}