Contracts 📃

Contracts are detected as soon as you connected a bank account or manually send the transactions for a user. If you have not done so yet, you can switch to Bank Accounts.

Requesting contracts

To retrieve the contracts of a user, you can use the me Query. For more information on what fields of a contract can be retrieved move to the Contract Models section.

{
    me {
        contracts {
            mainCategory
            subCategory
            amount
            figoTransactions{
                amount
                purpose
            }
        }
    }
}

Customizing a Contract

You can customize the properties of a contract to add additional information or to fix incorrectly guessed fields. This can be done by the customizeContract mutation. All cusomizable properties can be found in the Contract Models.

mutation {
  customizeContract(contractid: "<CONTRACT_ID>", input: {
    customName: "Foo"
  })
}

Manually Add Contract

If a contract wasn't automatically found by Yoli, you can also manually add it using the addContract mutation.

mutation {
  addContract(input: {customName: "Foo", customInterval: "MONTHLY", customAmount: 123456}) {
    contractid
  }
}

Deleting a Contract

Since actually deleting a contract would just cause it to be found again on the next analysis of the account, contract should rather be hidden than deleted most of the time. Hiding them causes them to be ignored by the api, except when explicitly asked to not be.

You can hide contracts with the customizeContract mutation.

mutation {
  customizeContract(contractid: "<CONTRACT_ID>", hidden: true)
}

Switching contracts

Switch contracts can be done via our partners Verivox and ComAds.

Terminating a Contract

The termination of a contract can happen on two different ways which are listed below. A prerequisite for both is that the contract is terminable.

PDF download

In order to send a termination yourself, a PDF template can be created and downloaded. This is done via the following HTTP GET endpoint:

../next/terminateContract/<CONTRACT_ID>/<INPUT>

The header of the request must always contains an access token (token). The data model of the parameter INPUT (URI format) is explained below.

{
    terminationTimestamp: "<TIMESTAMP>",
    user: {
        name: "<USER_NAME>",
        address: "<USER_ADDRESS>",
        postCode: "<USER_POSTCODE>",
        city: "<USER_CITY>",
        email: "<USER_EMAIL>",
        birthDate: "<USER_BIRTHDATE>"
    },
    partner: {
        name: "<PARTNER_NAME>",
        address: "<PARTNER_ADDRESS>",
        postCode: "<PARTNER_POSTCODE>",
        city: "<PARTNER_CITY>",
    }
}

If no termination date is specified (terminationTimestamp), the next possible time is automatically noted on the termination letter. At the first request an INPUT object must be given. In order to download the document for this contract in the future again, no INPUT object has to be sent along.

Termination by fax

A fax will be sent via this mutation with the termination letter to the associated contract partner. A fax number must be available for the contract partner! If no termination date is specified (terminationTimestamp), the next possible time is automatically noted on the termination letter. Note: The fields signature and ContractTerminationInput.Partner (not shown below) are obsolete and will be removed in the future.

mutation {
    terminateContractFax(contractId: "<CONTRACT_ID>", input: {
        terminationTimestamp: "<TIMESTAMP>",
        user: {
            name: "<USER_NAME>",
            address: "<USER_ADDRESS>",
            postCode: "<USER_POSTCODE>",
            city: "<USER_CITY>",
            email: "<USER_EMAIL>",
            birthDate: "<USER_BIRTHDATE>"
        }
    })
}

PDF templates for contract termination rejection

Via this HTTP GET endpoint, different templates can be downloaded when the contract partner rejects the termination. Only an access token must be provided in the request header (token) but no other parameters are needed.

../next/terminateContractFaq

Requesting contract categories

To retrieve all contract categories for your brand, the contractCategories query can be used. This query returns an array of categories and their associated mainCategory and subCategory which are translatable fields:

query {
    contractCategories {
        mainCategory
        subCategory
    }
}

Contract Models

Contract

type Contract {
    # main category as automatically detected
    mainCategory: Translatable

    # sub category as automatically detected
    subCategory: Translatable

    # main category as set by user
    customMainCategory: Translatable

    # sub category as set by user
    customSubCategory: Translatable

    # contract's group as set by user
    customGroup: String

    # name of contract as set by user
    customName: String

    # custom contract id
    customCid: String

    # contract partner as set by user
    customContractPartner: CustomContractPartner

    # parent contract, if this is a sub contract of a multi contract
    parentContract: String

    # this is a contract with multiple sub contracts
    isMultiContract: Boolean

    # For how many months will the contract be extended if cancelation deadline is exceeded? 
    extensionPeriod: Int

    # ISO date of contract end date
    runTime: String

    # How many months before the end of the runtime can you cancel the contract?
    periodOfNotice: Int

    # predicated date of the next booking
    nextBooking: String

    # Should the user be notified of an incoming period of notice?
    cancelationAlert: Boolean

    # True if the user has customized this contract
    configured: Boolean

    # True if the user has seen this contract
    seen: Boolean

    # is  the contract hidden (deleted)
    hidden: Boolean

    # is this a contract that has ended
    isActive: Boolean

    # is created by user
    createdByUser: Boolean

    # is terminated
    terminated: Boolean

    # whether the contract is terminable via our api
    terminable: Boolean

    # Custom details the user has set
    details: [DetailResult]

    # account this is connected to
    account: Account

    # id of account this is connected to
    accountId: String

    # unique id of the contract
    contractid: String

    # amount of the contract per interval in cent
    amount: Int

    # recurrence: WEEKLY, BIWEEKLY, MONTHLY, BIMONTHLY, QUARTERLY, SEMIANNUALLY, ANNUALLY, (NONE if no interval was detected)
    interval: String

    tags: [String]

    # date the contract became active
    duration: Float # https://github.com/graphql/graphql-js/issues/292#issuecomment-186702763 recommends to use floats for big ints :/

    # contractor category - probably shouldn't use this
    category: String

    # contract partner is (NOT contractid)
    cid: String

    # sepa reference
    mref: String

    # information about the contract termination
    termination: ContractTerminationInfo

    # the contract partner
    contractPartner: ContractPartner

    # all sub contracts of this contract
    subContracts: [Contract]

    # transactions
    figoTransactions(search: String): [Transaction]

    # DEPRECATED! Use figoTransactions instead!
    transactions: [ContractTransaction]

    # an array of all transaction ids concatenated with the respective account ids
    contractorTransactions: [String]
}

Payment Partner Payload

type PaymentPartnerPayload {
    # payment partner name
    name: String

    # creditor id
    creditorId: String

    # score of search result
    score: Float

    # payment partner id
    paymentPartnerId: String
}

Contract Partner

type ContractPartner {
    # contract partner creditor id
    creditorId: String

    # human readable name of contract partner
    name: String

    # street and house number
    address: String

    # postcode of contract partner
    postcode: String

    # city where partner resides
    city: String

    # email of contract partner
    email: String

    # phone number of contract partner
    phone: String

    # fax number of contract partner
    fax: String

    # website of contract partner
    www: String

    # tags that describe this contract partner
    tags: [String]
}

Custom Contract Partner

type CustomContractPartner {
    creditorId: String

    # human readable name of contract partner
    name: String

    # street and house number
    address: String

    # postcode of contract partner
    postcode: String

    # city where partner resides
    city: String

    # email of contract partner
    email: String

    # phone number of contract partner
    phone: String

    # fax number of contract partner
    fax: String

    # website of contract partner
    www: String
}

Custom Partner

type CustomPartner {
    creditorId: String

    # human readable name of contract partner
    name: String

    # street and house number
    address: String

    # postcode of contract partner
    postCode: String

    # city where partner resides
    city: String

    # email of contract partner
    email: String

    # phone number of contract partner
    phone: String

    # fax number of contract partner
    fax: String

    # website of contract partner
    www: String

    # a specified contract number of contract termination
    contractNumber: String
}

Custom Contract Partner Input

input CustomContractPartnerInput {
    creditorId: String

    # human readable name of contract partner
    name: String

    # street and house number
    address: String

    # postcode of contract partner
    postcode: String

    # city where partner resides
    city: String

    # email of contract partner
    email: String
}

Custom Partner Input

input CustomPartnerInput {
    creditorId: String

    # human readable name of contract partner
    name: String

    # street and house number
    address: String

    # postcode of contract partner
    postCode: String

    # city where partner resides
    city: String

    # email of contract partner
    email: String
}

Contract Input

input ContractInput {
    # user set name
    customName: String

    # user set main category
    customMainCategory: String

    # user set sub category
    customSubCategory: String

    # user set group
    customGroup: String

    # whether the contract is visible
    hidden: Boolean

    # connected documents
    documents: [String]

    # sets a user defined contract partner
    customContractPartner: CustomContractPartnerInput

    extensionPeriod: Int

    # how many months the contract is valid
    runTime: String

    # how many months the user has to cancel the contract before it auto renews
    periodOfNotice: Int

    # whether the user has approved the contracts' details
    configured: Boolean

    # whether the user has seen the contract
    seen: Boolean

    # whether or not the alert the user about nearing period of notice
    cancelationAlert: Boolean

    # account this contract will be linked to
    accountId: String

    # user set amount
    customAmount: Int

    # user set interval
    customInterval: String

    # parent contract, if this is a sub contract of a multi contract
    parentContract: String

    # this is a contract with multiple sub contracts
    isMultiContract: Boolean

    # transactions connected to the account
    transactions: [TransactionInput]
}

Contract Termination

type ContractTermination {
    # the user address
    user: UserAddress

    # the contract partner address
    partner: CustomPartner
}

Contract Termination Info

type ContractTerminationInfo {
    # the user selected way to terminate the contract
    type: String

    # the date of the contract termination
    date: String
}

Missing Contract Termination Fields

type MissingContractTerminationFields {
    # missing user fields of the user address
    userAddress: [String]

    # missing fields of the contract partner address
    partnerAddress: [String]
}

Contract Termination Input

input ContractTerminationInput {
    # the user address
    user: UserAddressInput

    # the contract partner address
    partner: CustomPartnerInput

    # timestamp in ms (null for next possible time)
    terminationTimestamp : String
}