-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathlending.yaml
9292 lines (9006 loc) · 400 KB
/
lending.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
openapi: 3.1.0
servers:
- description: Production
url: 'https://api.codat.io'
info:
title: Lending API
description: |-
Our Lending API helps you make smarter credit decisions on small businesses by enabling you to pull your customers' latest data from accounting, banking, and commerce platforms they are already using. It also includes features to help providers verify the accuracy of data and process it more efficiently.
The Lending API is built on top of the latest accounting, commerce, and banking data, providing you with the most important data points you need to get a full picture of SMB creditworthiness and make a comprehensive assessment of your customers.
[Explore product](https://docs.codat.io/lending/overview) | [See OpenAPI spec](https://github.com/codatio/oas)
<!-- Start Codat Tags Table -->
## Endpoints
| Endpoints | Description |
| :- |:- |
| Companies | Create and manage your SMB users' companies. |
| Connections | Create new and manage existing data connections for a company. |
| Bank statements | Retrieve banking data from linked bank accounts. |
| Sales | Retrieve standardized sales data from a linked commerce platform. |
| Financial statements | Financial data and reports from a linked accounting platform. |
| Liabilities | Debt and other liabilities. |
| Accounts payable | Data from a linked accounting platform representing money the business owes money to its suppliers. |
| Accounts receivable | Data from a linked accounting platform representing money owed to the business for sold goods or services. |
| Transactions | Data from a linked accounting platform representing transactions. |
| Company info | View company information fetched from the source platform. |
| Data integrity | Match mutable accounting data with immutable banking data to increase confidence in financial data. |
| Excel reports | Download reports in Excel format. |
| Manage data | Control how data is retrieved from an integration. |
| File upload | Endpoints to manage uploaded files. |
| Loan writeback | Implement the [loan writeback](https://docs.codat.io/lending/guides/loan-writeback/introduction) procedure in your lending process to maintain an accurate position of a loan during the entire lending cycle. |
<!-- End Codat Tags Table -->
version: 3.0.0
contact:
name: Codat
email: [email protected]
termsOfService: 'https://www.codat.io/legals/'
security:
- auth_header: []
x-speakeasy-retries:
strategy: backoff
backoff:
initialInterval: 500
maxInterval: 60000
maxElapsedTime: 3600000
exponent: 1.5
statusCodes:
- 408
- 429
- 5XX
retryConnectionErrors: true
x-speakeasy-name-override:
- operationId: ^list-.*?
methodNameOverride: list
- operationId: ^list-.*?-attachments
methodNameOverride: list-attachments
- operationId: ^get-.*?
methodNameOverride: get
- operationId: ^get-create-.*?-model
methodNameOverride: get-create-model
- operationId: ^get-create-update.*?-model
methodNameOverride: get-create-update-model
- operationId: ^get-.*?-attachment
methodNameOverride: get-attachment
- operationId: ^update-.*?
methodNameOverride: update
- operationId: ^create-.*?
methodNameOverride: create
- operationId: ^delete-.*?
methodNameOverride: delete
- operationId: ^delete-.*?-attachment
methodNameOverride: delete-attachment
- operationId: ^download-.*?-attachment
methodNameOverride: download-attachment
- operationId: ^upload-.*?-attachment
methodNameOverride: upload-attachment
x-codat-docs-path: lending-api
x-codat-keep-docs-paths-local: true
x-codat-speakeasy-pagination:
type: offsetLimit
inputs:
- name: page
in: parameters
type: page
outputs:
results: $.results
tags:
- name: Companies
description: Create and manage your SMB users' companies.
- name: Connections
description: Create new and manage existing data connections for a company.
- name: Bank statements
description: Retrieve banking data from linked bank accounts.
- name: Sales
description: Retrieve standardized sales data from a linked commerce platform.
- name: Financial statements
description: Financial data and reports from a linked accounting platform.
- name: Liabilities
description: Debt and other liabilities.
- name: Accounts payable
description: Data from a linked accounting platform representing money the business owes money to its suppliers.
- name: Accounts receivable
description: Data from a linked accounting platform representing money owed to the business for sold goods or services.
- name: Accounting bank data
description: Access bank transactions from an accounting platform.
- name: Transactions
description: Data from a linked accounting platform representing transactions.
- name: Company info
description: View company information fetched from the source platform.
- name: Data integrity
description: Match mutable accounting data with immutable banking data to increase confidence in financial data.
- name: Excel reports
description: Download reports in Excel format.
- name: Manage data
description: Control how data is retrieved from an integration.
- name: File upload
description: Endpoints to manage uploaded files.
- name: Loan writeback
description: 'Implement the [loan writeback](https://docs.codat.io/lending/guides/loan-writeback/introduction) procedure in your lending process to maintain an accurate position of a loan during the entire lending cycle.'
paths:
/companies:
get:
summary: List companies
tags:
- Companies
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Companies'
examples:
One company:
value:
results:
- id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
name: My Test Company
description: My Test Company make testing software
platform: ''
redirect: 'https://link.codat.io/company/3fa85f64-5717-4562-b3fc-2c963f66afa6'
lastSync: '2022-01-01T12:30:00.000Z'
dataConnections:
- id: 51baa045-4836-4317-a42e-3542e991e581
integrationId: 1c312d69-e638-46d4-ad31-72e6c3ba8390
integrationKey: vjms
sourceId: 396c3158-5dd7-481b-a7c4-a795ca31792b
platformName: Pandle
linkUrl: 'https://link-api.codat.io/companies/3fa85f64-5717-4562-b3fc-2c963f66afa6/connections/51baa045-4836-4317-a42e-3542e991e581/start'
status: Linked
lastSync: '2022-01-01T12:30:00.000Z'
created: '2022-01-01T11:30:00Z'
sourceType: Accounting
created: '2022-01-01T11:30:00Z'
createdByUserName: Mike Smith
groups:
- id: d7a6c4b4-dc87-45f6-b803-62f466398680
pageNumber: 1
pageSize: 100
totalResults: 1
_links:
current:
href: /companies?page=1&pageSize=100
self:
href: /companies
List of Companies:
value:
results:
- id: d1568dde-adf6-11ed-afa1-0242ac120002
name: Technicalium
description: 'Technology services, including web and app design and development'
platform: ''
redirect: 'https://link.codat.io/company/d1568dde-adf6-11ed-afa1-0242ac120002'
lastSync: '2022-01-01T12:30:00.000Z'
dataConnections:
- id: 51baa045-4836-4317-a42e-3542e991e581
integrationId: 1c312d69-e638-46d4-ad31-72e6c3ba8390
integrationKey: vjms
sourceId: 396c3158-5dd7-481b-a7c4-a795ca31792b
platformName: Pandle
linkUrl: 'https://link-api.codat.io/companies/d1568dde-adf6-11ed-afa1-0242ac120002/connections/51baa045-4836-4317-a42e-3542e991e581/start'
status: Linked
lastSync: '2022-01-01T12:30:00.000Z'
created: '2022-01-01T11:30:00Z'
sourceType: Accounting
created: '2022-01-01T11:30:00Z'
createdByUserName: Joe Bloggs
- id: 096db70b-78de-4ff0-aa98-299cb5fe17a0
name: Godata
description: A new digital agency with a passion for creating amazing digital experiences
platform: ''
redirect: 'https://link.codat.io/company/096db70b-78de-4ff0-aa98-299cb5fe17a0'
lastSync: '2022-01-01T12:30:00.000Z'
dataConnections:
- id: a70bc148-dc21-46b2-a257-d9c58ac15cbb
integrationId: 1c312d69-e638-46d4-ad31-72e6c3ba8390
integrationKey: vjms
sourceId: 396c3158-5dd7-481b-a7c4-a795ca31792b
platformName: Pandle
linkUrl: 'https://link-api.codat.io/companies/096db70b-78de-4ff0-aa98-299cb5fe17a0/connections/a70bc148-dc21-46b2-a257-d9c58ac15cbb/start'
status: Linked
lastSync: '2022-01-01T12:30:00.000Z'
created: '2022-01-01T11:30:00Z'
sourceType: Accounting
created: '2022-01-01T11:30:00Z'
createdByUserName: Mike Smith
pageNumber: 1
pageSize: 100
totalResults: 2
_links:
current:
href: /companies?page=1&pageSize=100
self:
href: /companies
'400':
$ref: '#/components/responses/Malformed-Query'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/Payment-Required'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
operationId: list-companies
description: "\uFEFFThe *List companies* endpoint returns a list of [companies] associated to your instances.\n\nA [company](https://docs.codat.io/lending-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/lending-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data."
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/query'
- $ref: '#/components/parameters/orderBy'
post:
summary: Create company
tags:
- Companies
operationId: create-company
responses:
'200':
description: OK
content:
application/json:
x-speakeasy-usage-example: true
schema:
$ref: '#/components/schemas/Company'
examples:
With no description:
value:
id: ab12c58d-a678-4ebf-a159-ae99e1807bd0
name: Technicalium
description: ''
platform: ''
redirect: 'https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0'
dataConnections: []
created: '2022-11-10T10:45:18.1950523Z'
createdByUserName: Dan Tzabar
With a description:
value:
id: ab12c58d-a678-4ebf-a159-ae99e1807bd0
name: Technicalium
description: 'Technology services, including web and app design and development'
platform: ''
redirect: 'https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0'
dataConnections: []
created: '2022-11-10T10:45:18.1950523Z'
createdByUserName: Dan Tzabar
With a group:
value:
id: ab12c58d-a678-4ebf-a159-ae99e1807bd0
name: Technicalium
description: ''
platform: ''
redirect: 'https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0'
dataConnections: []
created: '2022-11-10T10:45:18.1950523Z'
createdByUserName: Dan Tzabar
groups:
- id: f8a6f6ed-9812-4d1e-ba48-4346348403c8
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/Payment-Required'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
description: "\uFEFFUse the *Create company* endpoint to create a new [company](https://docs.codat.io/lending-api#/schemas/Company) that represents your customer in Codat. \n\nA [company](https://docs.codat.io/lending-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/lending-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data.\n\nIf forbidden characters (see `name` pattern) are present in the request, a company will be created with the forbidden characters removed. For example, `Company (Codat[1])` with be created as `Company Codat1`."
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyRequestBody'
examples:
With no description:
value:
name: Technicalium
With a description:
value:
name: Technicalium
description: 'Technology services, including web and app design and development'
With a group:
value:
name: Technicalium
groups:
- id: d7a6c4b4-dc87-45f6-b803-62f466398680
'/companies/{companyId}':
put:
summary: Update company
description: "\uFEFFUse the *Update company* endpoint to update both the name and description of the company. \nIf you use [groups](https://docs.codat.io/lending-api#/schemas/Group) to manage a set of companies, use the [Add company](https://docs.codat.io/lending-api#/operations/add-company-to-group) or [Remove company](https://docs.codat.io/lending-api#/operations/remove-company-from-group) endpoints to add or remove a company from a group.\n\nA [company](https://docs.codat.io/lending-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/lending-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data."
operationId: update-company
parameters:
- $ref: '#/components/parameters/companyId'
tags:
- Companies
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Company'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/Payment-Required'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyRequestBody'
examples:
Update name:
value:
name: New Name
Update description:
value:
name: Same name
description: Additional documents required
delete:
summary: Delete a company
operationId: delete-company
parameters:
- $ref: '#/components/parameters/companyId'
description: "\uFEFFThe *Delete company* endpoint permanently deletes a [company](https://docs.codat.io/lending-api#/schemas/Company), its [connections](https://docs.codat.io/lending-api#/schemas/Connection) and any cached data. This operation is irreversible.\n\nA [company](https://docs.codat.io/lending-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/lending-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data.\n"
tags:
- Companies
responses:
'204':
description: No Content
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/Payment-Required'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
get:
summary: Get company
operationId: get-company
description: "\uFEFFThe *Get company* endpoint returns a single company for a given `companyId`.\n\nA [company](https://docs.codat.io/lending-api#/schemas/Company) represents a business sharing access to their data.\nEach company can have multiple [connections](https://docs.codat.io/lending-api#/schemas/Connection) to different data sources, such as one connection to Xero for accounting data, two connections to Plaid for two bank accounts, and a connection to Zettle for POS data.\n"
parameters:
- $ref: '#/components/parameters/companyId'
tags:
- Companies
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Company'
examples:
Simple company:
value:
id: ab12c58d-a678-4ebf-a159-ae99e1807bd0
name: My First Company
description: ''
platform: ''
redirect: 'https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0'
dataConnections: []
created: '2022-11-10T10:45:18Z'
createdByUserName: Dan Tzabar
With groups:
value:
id: ab12c58d-a678-4ebf-a159-ae99e1807bd0
name: My First Company
description: ''
platform: ''
redirect: 'https://link.codat.io/company/ab12c58d-a678-4ebf-a159-ae99e1807bd0'
dataConnections: []
created: '2022-11-10T10:45:18Z'
createdByUserName: Dan Tzabar
groups:
- id: f8a6f6ed-9812-4d1e-ba48-4346348403c8
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/Payment-Required'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/Not-Found'
'429':
$ref: '#/components/responses/Too-Many-Requests'
'500':
$ref: '#/components/responses/Internal-Server-Error'
'503':
$ref: '#/components/responses/Service-Unavailable'
components:
schemas:
AccountCategoriesUpdatedWebhook:
title: Account categories updated webhook
description: Webhook request body for the "Account categories updated" event.
x-internal: true
type: object
properties:
ClientId:
$ref: '#/components/schemas/ClientRateLimitResetWebhook/properties/ClientId'
ClientName:
$ref: '#/components/schemas/ClientRateLimitResetWebhook/properties/ClientName'
CompanyId:
$ref: '#/components/parameters/companyId/schema'
DataConnectionId:
$ref: '#/components/parameters/connectionId/schema'
RuleId:
$ref: '#/components/schemas/ClientRateLimitResetWebhook/properties/RuleId'
RuleType:
$ref: '#/components/schemas/ClientRateLimitResetWebhook/properties/RuleType'
AlertId:
$ref: '#/components/schemas/ClientRateLimitResetWebhook/properties/AlertId'
Message:
$ref: '#/components/schemas/ClientRateLimitResetWebhook/properties/Message'
Data:
$ref: '#/components/schemas/AccountCategoriesUpdatedWebhook/definitions/AccountCategoriesUpdatedWebhookData'
definitions:
AccountCategoriesUpdatedWebhookData:
type: object
title: Account categories updated webhook data
properties:
modifiedDate:
description: The date on which the company's account categories were last modified in Codat.
type: string
example: '2022-10-23'
title: Date
examples:
- ClientId: bae71d36-ff47-420a-b4a6-f8c9ddf41140
ClientName: Bank of Dave
CompanyId: 8a210b68-6988-11ed-a1eb-0242ac120002
DataConnectionId: 2e9d2c44-f675-40ba-8049-353bfcb5e171
RuleId: 70af3071-65d9-4ec3-b3cb-5283e8d55dac
RuleType: Account Categories Updated
AlertId: a9367074-b5c3-42c4-9be4-be129f43577e
Message: Account categories updated for company f1c35bdc-1546-41b9-baf4-3f31135af968.
Data:
modifiedDate: '2019-08-24T14:15:22Z'
AccountingAccount:
title: 'Accounting: Account'
description: "\uFEFF> **Language tip:** Accounts are also referred to as **chart of accounts**, **nominal accounts**, and **general ledger**.\n\nView the coverage for accounts in the <a className=\"external\" href=\"https://knowledge.codat.io/supported-features/accounting?view=tab-by-data-type&dataType=chartOfAccounts\" target=\"_blank\">Data coverage explorer</a>.\n\n## Overview\n\nAccounts are the categories a business uses to record accounting transactions. From the Accounts endpoints, you can retrieve a list of all accounts for a specified company.\n\nThe categories for an account include:\n* Asset\n* Expense\n* Income\n* Liability\n* Equity.\n\nThe same account may have a different category based on the integration it is used in. For example, a current account (known as checking in the US) should be categorized as `Asset.Current` for Xero, and `Asset.Bank.Checking` for QuickBooks Online.\n\nAt the same time, each integration may have its own requirements to the categories. For example, a Paypal account in Xero is of the `Asset.Bank` category and therefore requires additional properties to be provided.\n\nTo determine the list of allowed categories for a specific integration, you can:\n- Follow our [Create, update, delete data](https://docs.codat.io/using-the-api/push) guide and use the [Get create account model](https://docs.codat.io/lending-api#/operations/get-create-chartOfAccounts-model).\n- Refer to the integration's own documentation.\n\n> **Accounts with no category**\n>\n> If an account is pulled from the chart of accounts and its nominal code does not lie within the category layout for the company's accounts, then the **type** is `Unknown`. The **fullyQualifiedCategory** and **fullyQualifiedName** fields return `null`.\n>\n> This approach gives a true representation of the company's accounts whilst preventing distorting financials such as a company's profit and loss and balance sheet reports."
allOf:
- properties:
id:
type: string
description: 'Identifier for the account, unique for the company.'
example: 1b6266d1-1e44-46c5-8eb5-a8f98e03124e
- $ref: '#/components/schemas/AccountingAccount/definitions/accountPrototype'
- properties:
metadata:
$ref: '#/components/schemas/Metadata'
- $ref: '#/components/schemas/CommerceOrder/allOf/3'
definitions:
accountPrototype:
title: Account prototype
type: object
properties:
nominalCode:
type: string
nullable: true
description: Reference given to each nominal account for a business. It ensures money is allocated to the correct account. This code isn't a unique identifier in the Codat system.
example: '610'
name:
type: string
nullable: true
description: Name of the account.
example: Accounts Receivable
description:
type: string
nullable: true
description: Description for the account.
example: Invoices the business has issued but has not yet collected payment on.
fullyQualifiedCategory:
type: string
nullable: true
description: "Full category of the account. \r\n\r\nFor example, `Liability.Current` or `Income.Revenue`. To determine a list of possible categories for each integration, see our examples, follow our [Create, update, delete data](https://docs.codat.io/using-the-api/push) guide, or refer to the integration's own documentation."
example: Asset.Current
fullyQualifiedName:
type: string
nullable: true
description: |-
Full name of the account, for example:
- `Cash On Hand`
- `Rents Held In Trust`
- `Fixed Asset`
examples:
- Cash On Hand
- Fixed Asset
currency:
$ref: '#/components/schemas/AgedCurrencyOutstanding/properties/currency'
currentBalance:
type: number
format: decimal
nullable: true
description: Current balance in the account.
example: 0
type:
$ref: '#/components/schemas/AccountingAccount/definitions/accountType'
status:
$ref: '#/components/schemas/AccountingAccount/definitions/accountStatus'
isBankAccount:
type: boolean
description: Confirms whether the account is a bank account or not.
validDatatypeLinks:
type: array
nullable: true
description: 'The validDatatypeLinks can be used to determine whether an account can be correctly mapped to another object; for example, accounts with a `type` of `income` might only support being used on an Invoice and Direct Income. For more information, see [Valid Data Type Links](/lending-api#/schemas/ValidDataTypeLinks).'
items:
title: Valid data type links
description: |-
When querying Codat's data model, some data types return `validDatatypeLinks` metadata in the JSON response. This indicates where that object can be used as a reference—a _valid link_—when creating or updating other data.
For example, `validDatatypeLinks` might indicate the following references:
- Which tax rates are valid to use on the line item of a bill.
- Which items can be used when creating an invoice.
You can use `validDatatypeLinks` to present your SMB customers with only valid choices when selecting objects from a list, for example.
## `validDatatypeLinks` example
The following example uses the `Accounting.Accounts` data type. It shows that, on the linked integration, this account is valid as the account on a payment or bill payment; and as the account referenced on the line item of a direct income or direct cost. Because there is no valid link to Invoices or Bills, using this account on those data types will result in an error.
```json validDatatypeLinks for an account
{
"id": "bd9e85e0-0478-433d-ae9f-0b3c4f04bfe4",
"nominalCode": "090",
"name": "Business Bank Account",
#...
"validDatatypeLinks": [
{
"property": "Id",
"links": [
"Payment.AccountRef.Id",
"BillPayment.AccountRef.Id",
"DirectIncome.LineItems.AccountRef.Id",
"DirectCost.LineItems.AccountRef.Id"
]
}
]
}
```
## Support for `validDatatypeLinks`
Codat currently supports `validDatatypeLinks` for some data types on our Xero, QuickBooks Online, QuickBooks Desktop, Exact (NL), and Sage Business Cloud integrations.
If you'd like us to extend support to more data types or integrations, suggest or vote for this on our <a href="https://portal.productboard.com/codat/5-product-roadmap">Product Roadmap</a>.
type: object
properties:
property:
type: string
nullable: true
description: The property from the account that can be linked.
links:
type: array
nullable: true
description: Supported `dataTypes` that the record can be linked to.
items:
type: string
supplementalData:
$ref: '#/components/schemas/SupplementalData'
accountRef:
title: Account reference
type: object
description: 'Data types that reference an account, for example bill and invoice line items, use an accountRef that includes the ID and name of the linked account.'
properties:
id:
type: string
description: '''id'' from the Accounts data type.'
name:
type: string
description: '''name'' from the Accounts data type.'
accountType:
title: Account type
enum:
- Unknown
- Asset
- Expense
- Income
- Liability
- Equity
type: string
description: Type of account
example: Asset
accountStatus:
title: Account status
enum:
- Unknown
- Active
- Archived
- Pending
type: string
description: Status of the account
example: Active
type: object
AccountingAccounts:
title: 'Accounting: Accounts'
x-internal: true
allOf:
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/AccountingAccount'
- $ref: '#/components/schemas/PagingInfo'
AccountingAccountTransaction:
title: 'Accounting: Account transaction'
description: |-
> **Language tip:** In Codat, account transactions represent all transactions posted to a bank account within an accounting platform. For bank transactions posted within a banking platform, refer to [Banking transactions](https://docs.codat.io/lending-api#/operations/list-all-banking-transactions).
> View the coverage for account transactions in the <a className="external" href="https://knowledge.codat.io/supported-features/accounting?view=tab-by-data-type&dataType=accountTransactions" target="_blank">Data coverage explorer</a>.
## Overview
In Codat’s data model, account transactions represent bank activity within an accounting platform. All transactions that go through a bank account are recorded as account transactions.
Account transactions are created as a result of different business activities, for example:
* Payments: for example, receiving money for payment against an invoice.
* Bill payments: for example, spending money for a payment against a bill.
* Direct costs: for example, withdrawing money from a bank account, either for cash purposes or to make a payment.
* Direct incomes: for example, selling an item directly to a contact and receiving payment at point of sale.
* Transfers: for example, transferring money between two bank accounts.
Account transactions is the parent data type of [payments](https://docs.codat.io/lending-api#/schemas/Payment), [bill payments](https://docs.codat.io/lending-api#/schemas/BillPayment), [direct costs](https://docs.codat.io/lending-api#/schemas/DirectCost), [direct incomes](https://docs.codat.io/lending-api#/schemas/DirectIncome), and [transfers](https://docs.codat.io/lending-api#/schemas/Transfer).
type: object
allOf:
- type: object
properties:
id:
type: string
description: Identifier of the direct cost (unique to the company).
transactionId:
type: string
nullable: true
description: Identifier of the transaction (unique to the company).
note:
type: string
nullable: true
description: 'Additional information about the account transaction, if available.'
bankAccountRef:
$ref: '#/components/schemas/AccountingBankAccount/definitions/bankAccountRef'
description: Reference to the bank account the account transaction is recorded against.
date:
$ref: '#/components/schemas/DateTime'
description: The date the account transaction was recorded in the platform.
status:
enum:
- Unknown
- Unreconciled
- Reconciled
- Void
type: string
description: The status of the account transaction.
currency:
$ref: '#/components/schemas/AgedCurrencyOutstanding/properties/currency'
currencyRate:
$ref: '#/components/schemas/AccountingPaymentAllocation/definitions/paymentAllocationPayment/properties/currencyRate'
lines:
type: array
nullable: true
description: Array of account transaction lines.
items:
$ref: '#/components/schemas/AccountingAccountTransaction/definitions/accountTransactionLine'
totalAmount:
type: number
format: decimal
description: 'Total amount of the account transactions, inclusive of tax.'
metadata:
$ref: '#/components/schemas/Metadata'
- $ref: '#/components/schemas/CommerceOrder/allOf/3'
definitions:
accountTransactionLine:
type: object
properties:
description:
type: string
nullable: true
description: Description of the account transaction.
recordRef:
$ref: '#/components/schemas/AccountingAccountTransaction/definitions/accountTransactionLineRecordRef'
amount:
type: number
format: decimal
description: Amount in the bill payment currency.
accountTransactionLineRecordRef:
type: object
title: Record reference
description: Links an account transaction line to the underlying record that created it.
properties:
id:
type: string
description: '''id'' of the underlying record or data type.'
dataType:
type: string
description: Name of underlying data type.
enum:
- bankTransactions
- billCreditNotes
- billPayments
- bills
- creditNotes
- directCosts
- directIncomes
- invoices
- journalEntries
- payments
- transfers
example: transfers
AccountingAccountTransactions:
title: 'Accounting: Account transactions'
x-internal: true
allOf:
- type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/AccountingAccountTransaction'
- $ref: '#/components/schemas/PagingInfo'
AccountingAddress:
title: 'Accounting: Address'
x-internal: true
type: object
properties:
type:
$ref: '#/components/schemas/AccountingAddress/definitions/accountingAddressType'
line1:
type: string
nullable: true
description: Line 1 of the customer address.
line2:
type: string
nullable: true
description: Line 2 of the customer address.
city:
type: string
nullable: true
description: City of the customer address.
region:
type: string
nullable: true
description: Region of the customer address.
country:
type: string
nullable: true
description: Country of the customer address.
postalCode:
type: string
nullable: true
description: Postal code or zip code.
required:
- type
definitions:
accountingAddressType:
description: The type of the address
type: string
enum:
- Unknown
- Billing
- Delivery
AccountingAgedCreditorReport:
title: 'Accounting: Aged creditors report'
description: |-
The Aged Creditors report shows the total balance owed by a business to its suppliers over time.
You can generate it for a company based on recently synced data from your customers' accounting platforms. The report is available in the **Reports** tab in the Codat portal.
Total assets or liabilities are grouped into 30-day periods for each supplier, up to the current date. You can adjust the report date, period length, and number of periods to show on each report. The data can be grouped by customer or currency.
> It is not guaranteed that write-offs are included in the Aged Creditors report.
## Underlying data
The Aged Creditors report is generated from a set of required data types: [Suppliers](https://docs.codat.io/lending-api#/schemas/Supplier), [Bills](https://docs.codat.io/lending-api#/schemas/Bill), [Bill credit notes](https://docs.codat.io/lending-api#/schemas/BillCreditNote), and [Bill payments](https://docs.codat.io/lending-api#/schemas/BillPayment).
To generate the report, the underlying data types must have been synced within 24 hours of each other. Otherwise an error is displayed when you try to run the report. Sync the required data types by clicking the link in the error, and then run the report again.
> The Aged Creditor report runs based on the **issue dates** of the underlying data types rather than the due date.
## Accessing the Aged Creditors report in Portal
Apart from returning the report via the API as JSON and query, you can also return the Aged Creditors report in the Codat portal.
1. In the navigation bar, click **Companies**.
2. Click the name of the company you want to generate the report for. The company's data page is displayed.
3. Click the **Accounting** tab then click **Reports**.
4. Select **Aged Creditors**.
5. _(Optional)_ Edit the default reporting parameters.
a. You can change the report date in the **Date** box. By default, the report includes transactions that occurred up to, but not including, today's date. To include transactions for today, enter tomorrow's date.
b. In the **Period Length Days** box, select the default period length for each column (the default is 30 days).
b. In the **Number of Periods** box, enter the number of periods to show as columns in the report (the default is 4 periods).
6. To run the report, click **Load aged creditors**.
7. The report is generated and displayed at the bottom of the page.
The report will be grouped per supplier and depending on the periods requested. The details indicates whether the amounts owed come from outstanding bills or bill credit notes.
type: object
properties:
generated:
$ref: '#/components/schemas/DateTime'
description: Date and time the report was generated.
reportDate:
$ref: '#/components/schemas/DateTime'
description: Date the report is generated up to.
data:
type: array
description: Array of aged creditor.
items:
$ref: '#/components/schemas/AccountingAgedCreditorReport/definitions/agedCreditor'
examples:
- generated: '2022-10-23T00:00:00Z'
reportDate: '2022-10-23T00:00:00Z'
data:
- customerId: f594cefb-7750-4c3a-bab2-b5322026dee9
customerName: John Doe
agedCurrencyOutstanding:
- currency: GBP
agedOutstandingAmounts:
- fromDate: '2022-10-01T00:00:00Z'
toDate: '2022-10-31T00:00:00Z'
amount: 1547.5
details:
- name: Bills
amount: 1547.5
definitions:
agedCreditor:
title: Aged creditor
type: object
properties:
supplierId:
type: string
description: Supplier ID of the aged creditor.
example: f594cefb-7750-4c3a-bab2-b5322026dee9
supplierName:
type: string
description: Supplier name of the aged creditor.
example: John Doe
agedCurrencyOutstanding:
type: array
description: Array of aged creditors by currency.
items:
$ref: '#/components/schemas/AgedCurrencyOutstanding'
AccountingAgedDebtorReport:
type: object
title: 'Accounting: Aged debtors report'
description: |-
The Aged Debtors report shows the total outstanding balance due from customers to the business over time.
You can generate it for a company based on recently synced data from your customers' accounting platforms. The report is available in the **Reports** tab in the Codat portal.
Total assets or liabilities are grouped into 30-day periods for each customer, up to the current date. You can adjust the report date, period length, and number of periods to show on each report. The data can be grouped by customer or currency.
> It is not guaranteed that write-offs are included in the Aged Debtors report.
## Underlying data
The Aged Debtors report is generated from a set of required data types: [Customers](https://docs.codat.io/lending-api#/schemas/Customer), [Invoices](https://docs.codat.io/lending-api#/schemas/Invoice), [Credit notes](https://docs.codat.io/lending-api#/schemas/CreditNote), and [Payments](https://docs.codat.io/lending-api#/schemas/Payment).
To generate the report, the underlying data types must have been synced within 24 hours of each other. Otherwise an error is displayed when you try to run the report. Sync the required data types by clicking the link in the error, and then run the report again.
> The Aged Debtors report runs based on the **issue dates** of the underlying data types rather than the due date.
## Accessing the Aged Debtors report in Portal
Apart from returning the report via the API as JSON and query, you can also return the Aged Debtors report in the Codat portal.
1. In the navigation bar, click **Companies**.
2. Click the name of the company you want to generate the report for. The company's data page is displayed.
3. Click the **Accounting** tab then click **Reports**.
4. Select **Aged Debtors**.
5. _(Optional)_ Edit the default reporting parameters.
a. You can change the report date in the **Date** box. By default, the report includes transactions that occurred up to, but not including, today's date. To include transactions for today, enter tomorrow's date.
b. In the **Period Length Days** box, select the default period length for each column (the default is 30 days).
b. In the **Number of Periods** box, enter the number of periods to show as columns in the report (the default is 4 periods).
6. To run the report, click **Load aged debtors**.
7. The report is generated and displayed at the bottom of the page.
The report will be grouped per supplier and depending on the periods requested. The details indicates whether the amounts owed come from outstanding invoices or credit notes.
properties:
generated:
$ref: '#/components/schemas/DateTime'
description: Date and time the report was generated.
reportDate:
$ref: '#/components/schemas/DateTime'
description: Date the report is generated up to.
data:
type: array
description: Array of aged debtors.
items:
$ref: '#/components/schemas/AccountingAgedDebtorReport/definitions/agedDebtor'
definitions:
agedDebtor:
title: Aged debtor
type: object
properties:
customerId:
type: string
description: Customer ID of the aged debtor.
example: f594cefb-7750-4c3a-bab2-b5322026dee9
customerName:
type: string
description: Customer name of the aged debtor.
example: John Doe
agedCurrencyOutstanding:
type: array
description: Array of aged debtors by currency.
items:
$ref: '#/components/schemas/AgedCurrencyOutstanding'
examples:
- generated: '2022-10-23T00:00:00Z'
reportDate: '2022-10-23T00:00:00Z'
data:
- customerId: f594cefb-7750-4c3a-bab2-b5322026dee9
customerName: John Doe
agedCurrencyOutstanding:
- currency: GBP
agedOutstandingAmounts:
- fromDate: '2022-10-01T00:00:00Z'
toDate: '2022-10-31T00:00:00Z'
amount: 1547.5
details:
- name: Invoices
amount: 1547.5
AccountingAttachment:
title: 'Accounting: Attachment'
description: |
The Codat API supports pulling and pushing of file attachments for invoices, bills, direct costs, and direct incomes.
> **Retrieving attachments**
>
> If a company is authorized, you can query the Codat API to read, download, and upload attachments without requiring a fresh sync of data.
Unlike other data types, Codat doesn't support [sync settings](https://docs.codat.io/knowledge-base/advanced-sync-settings) for attachments.
Note that different integrations have different requirements to file size and extension of attachments.
| Integration | File size | File extension |
|-------------------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Xero | 4 MB | 7Z, BMP, CSV, DOC, DOCX, EML, GIF, JPEG, JPG, KEYNOTE, MSG, NUMBERS, ODF, ODS, ODT, PAGES, PDF, PNG, PPT, PPTX, RAR, RTF, TIF, TIFF, TXT, XLS, XLSX, ZIP |
| QuickBooks Online | 100 MB | AI, CSV, DOC, DOCX, EPS, GIF, JPEG, JPG, ODS, PAGES, PDF, PNG, RTF, TIF, TXT, XLS, XLSX, XML |
| NetSuite | 100 MB | BMP, CSV, XLS, XLSX, JSON, PDF, PJPG, PJPEG, PNG, TXT, SVG, TIF, TIFF, DOC, DOCX, ZIP |
| Dynamics 365 Business Central | 350 MB | Dynamics do not explicitly outline which file types are supported but they do state <a className="external" href="https://learn.microsoft.com/en-gb/dynamics365/business-central/ui-how-add-link-to-record#to-attach-a-file-to-a-purchase-invoice" target="_blank">here</a> that "You can attach any type of file, such as text, image, or video files". |
View the coverage for each integration in the <a className="external" href="https://knowledge.codat.io/supported-features/accounting" target="_blank">Data coverage explorer</a>.
type: object
allOf:
- type: object
properties:
id: